@rkarim08/sia 1.0.0

package/src/graph/communities.ts

@@ -0,0 +1,195 @@
+// Module: communities — Community CRUD layer with audit logging
+
+import { randomUUID } from "node:crypto";
+import { writeAuditEntry } from "@/graph/audit";
+import type { SiaDb } from "@/graph/db-interface";
+import type {
+	Community,
+	CommunityMember,
+	CommunitySummary,
+	InsertCommunityInput,
+	UpdateCommunityInput,
+} from "@/graph/types";
+
+/**
+ * Insert a new community into the graph database.
+ * Generates a UUID, sets created_at and updated_at to now.
+ * Writes an ADD entry to the audit log.
+ */
+export async function insertCommunity(db: SiaDb, input: InsertCommunityInput): Promise<Community> {
+	const now = Date.now();
+	const id = randomUUID();
+
+	const community: Community = {
+		id,
+		level: input.level,
+		parent_id: input.parent_id ?? null,
+		summary: null,
+		summary_hash: null,
+		member_count: 0,
+		last_summary_member_count: 0,
+		package_path: input.package_path ?? null,
+		created_at: now,
+		updated_at: now,
+	};
+
+	await db.execute(
+		`INSERT INTO communities (
+			id, level, parent_id, summary, summary_hash,
+			member_count, last_summary_member_count,
+			package_path, created_at, updated_at
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		[
+			community.id,
+			community.level,
+			community.parent_id,
+			community.summary,
+			community.summary_hash,
+			community.member_count,
+			community.last_summary_member_count,
+			community.package_path,
+			community.created_at,
+			community.updated_at,
+		],
+	);
+
+	await writeAuditEntry(db, "ADD", {});
+
+	return community;
+}
+
+/**
+ * Retrieve a single community by id.
+ * Returns the community or null if not found.
+ */
+export async function getCommunity(db: SiaDb, id: string): Promise<Community | null> {
+	const result = await db.execute("SELECT * FROM communities WHERE id = ?", [id]);
+	return (result.rows[0] as unknown as Community | undefined) ?? null;
+}
+
+/**
+ * Retrieve communities filtered by level and optional package path.
+ */
+export async function getCommunityByLevel(
+	db: SiaDb,
+	level: 0 | 1 | 2,
+	packagePath?: string | null,
+): Promise<Community[]> {
+	if (packagePath !== undefined && packagePath !== null) {
+		const result = await db.execute(
+			"SELECT * FROM communities WHERE level = ? AND package_path = ?",
+			[level, packagePath],
+		);
+		return result.rows as unknown as Community[];
+	}
+
+	const result = await db.execute("SELECT * FROM communities WHERE level = ?", [level]);
+	return result.rows as unknown as Community[];
+}
+
+/**
+ * Update partial fields on an existing community.
+ * Always updates updated_at to now.
+ * Writes an UPDATE entry to the audit log.
+ */
+export async function updateCommunity(
+	db: SiaDb,
+	id: string,
+	updates: UpdateCommunityInput,
+): Promise<void> {
+	const entries = Object.entries(updates).filter(([, v]) => v !== undefined);
+	const now = Date.now();
+
+	// Always update updated_at
+	const setClauses = [...entries.map(([key]) => `${key} = ?`), "updated_at = ?"].join(", ");
+	const values = [...entries.map(([, v]) => v), now];
+
+	await db.execute(`UPDATE communities SET ${setClauses} WHERE id = ?`, [...values, id]);
+
+	await writeAuditEntry(db, "UPDATE", {});
+}
+
+/**
+ * Add a member entity to a community.
+ * Uses INSERT OR IGNORE so duplicate adds are safe (idempotent).
+ */
+export async function addMember(
+	db: SiaDb,
+	communityId: string,
+	entityId: string,
+	level: 0 | 1 | 2,
+): Promise<void> {
+	await db.execute(
+		"INSERT OR IGNORE INTO community_members (community_id, entity_id, level) VALUES (?, ?, ?)",
+		[communityId, entityId, level],
+	);
+}
+
+/**
+ * Remove all members from a community.
+ * Used during Leiden algorithm re-runs to clear stale membership.
+ */
+export async function removeMembers(db: SiaDb, communityId: string): Promise<void> {
+	await db.execute("DELETE FROM community_members WHERE community_id = ?", [communityId]);
+}
+
+/**
+ * Retrieve all members of a community.
+ */
+export async function getMembers(db: SiaDb, communityId: string): Promise<CommunityMember[]> {
+	const result = await db.execute("SELECT * FROM community_members WHERE community_id = ?", [
+		communityId,
+	]);
+	return result.rows as unknown as CommunityMember[];
+}
+
+/**
+ * Retrieve community summaries (WHERE summary IS NOT NULL).
+ * Ordered by member_count DESC. Optionally filtered by level and limited.
+ */
+export async function getSummaries(
+	db: SiaDb,
+	level?: 0 | 1 | 2,
+	limit?: number,
+): Promise<CommunitySummary[]> {
+	let sql: string;
+	const params: Array<number | string> = [];
+
+	if (level !== undefined) {
+		sql =
+			"SELECT id, level, summary, member_count FROM communities WHERE summary IS NOT NULL AND level = ? ORDER BY member_count DESC";
+		params.push(level);
+	} else {
+		sql =
+			"SELECT id, level, summary, member_count FROM communities WHERE summary IS NOT NULL ORDER BY member_count DESC";
+	}
+
+	if (limit !== undefined) {
+		sql += " LIMIT ?";
+		params.push(limit);
+	}
+
+	const result = await db.execute(sql, params);
+
+	return (
+		result.rows as Array<{ id: string; level: 0 | 1 | 2; summary: string; member_count: number }>
+	).map((row) => ({
+		id: row.id,
+		level: row.level,
+		summary: row.summary,
+		member_count: row.member_count,
+		top_entities: [],
+	}));
+}
+
+/**
+ * Pure function: returns true if the community needs re-summarization.
+ * Triggered when the relative change in member count exceeds 20%.
+ * Formula: |member_count - last_summary_member_count| / max(last_summary_member_count, 1) > 0.20
+ */
+export function needsResummarization(community: Community): boolean {
+	const last = community.last_summary_member_count;
+	const current = community.member_count;
+	const change = Math.abs(current - last) / Math.max(last, 1);
+	return change > 0.2;
+}

package/src/graph/db-interface.ts

@@ -0,0 +1,259 @@
+// Module: db-interface — SiaDb interface and BunSqliteDb adapter
+
+import { Database, type SQLQueryBindings } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { SyncConfig } from "@/shared/config";
+import { SIA_HOME } from "@/shared/config";
+
+/** Returns true for SQL statements that produce rows (SELECT, PRAGMA, RETURNING, etc.) */
+function isReadStatement(sql: string): boolean {
+	const trimmed = sql.trimStart().toUpperCase();
+	return (
+		trimmed.startsWith("SELECT") ||
+		trimmed.startsWith("PRAGMA") ||
+		trimmed.startsWith("WITH") ||
+		trimmed.startsWith("EXPLAIN") ||
+		trimmed.includes("RETURNING")
+	);
+}
+
+/**
+ * Unified database adapter interface.
+ * All CRUD code writes against SiaDb, never directly against bun:sqlite or @libsql/client.
+ */
+export interface SiaDb {
+	execute(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+	executeMany(statements: Array<{ sql: string; params?: unknown[] }>): Promise<void>;
+	transaction(fn: (db: SiaDb) => Promise<void>): Promise<void>;
+	close(): Promise<void>;
+	rawSqlite(): Database | null;
+	sync?(): Promise<void>;
+}
+
+/**
+ * Bun:sqlite implementation of SiaDb (used when sync.enabled = false).
+ */
+export class BunSqliteDb implements SiaDb {
+	private inTransaction = false;
+
+	constructor(private readonly db: Database) {}
+
+	/** Internal: executes SQL without the reentrancy guard. Used by txProxy. */
+	private _executeRaw(sql: string, params: unknown[] = []): { rows: Record<string, unknown>[] } {
+		const stmt = this.db.prepare(sql);
+		if (isReadStatement(sql)) {
+			const rows = stmt.all(...(params as SQLQueryBindings[])) as Record<string, unknown>[];
+			return { rows };
+		}
+		stmt.run(...(params as SQLQueryBindings[]));
+		return { rows: [] };
+	}
+
+	async execute(sql: string, params: unknown[] = []): Promise<{ rows: Record<string, unknown>[] }> {
+		if (this.inTransaction) {
+			throw new Error(
+				"Cannot call execute() on outer db during active transaction() — use the transaction proxy",
+			);
+		}
+		return this._executeRaw(sql, params);
+	}
+
+	async executeMany(statements: Array<{ sql: string; params?: unknown[] }>): Promise<void> {
+		if (this.inTransaction) {
+			throw new Error(
+				"Cannot call executeMany() on outer db during active transaction() — use the transaction proxy",
+			);
+		}
+		this.db.prepare("BEGIN").run();
+		try {
+			for (const { sql, params = [] } of statements) {
+				this.db.prepare(sql).run(...(params as SQLQueryBindings[]));
+			}
+			this.db.prepare("COMMIT").run();
+		} catch (e) {
+			this.db.prepare("ROLLBACK").run();
+			throw e;
+		}
+	}
+
+	async transaction(fn: (db: SiaDb) => Promise<void>): Promise<void> {
+		// bun:sqlite's db.transaction() is synchronous — passing an async callback
+		// would commit before awaited operations complete (torn writes).
+		// Instead, manage transaction boundaries explicitly around the async fn.
+		//
+		// Pass a proxy to fn rather than `this` so that any nested call to
+		// txProxy.transaction() throws immediately with a clear error message,
+		// matching LibSqlDb's behaviour.
+		// txProxy calls _executeRaw directly to bypass the reentrancy guard.
+		const txProxy: SiaDb = {
+			execute: (sql, params) => Promise.resolve(this._executeRaw(sql, params)),
+			executeMany: async (stmts) => {
+				for (const { sql, params = [] } of stmts) {
+					this._executeRaw(sql, params);
+				}
+			},
+			transaction: () => {
+				throw new Error("Nested transactions not supported");
+			},
+			close: async () => {},
+			rawSqlite: () => this.db,
+		};
+		this.inTransaction = true;
+		this.db.prepare("BEGIN").run();
+		try {
+			await fn(txProxy);
+			this.db.prepare("COMMIT").run();
+		} catch (e) {
+			this.db.prepare("ROLLBACK").run();
+			throw e;
+		} finally {
+			this.inTransaction = false;
+		}
+	}
+
+	async close(): Promise<void> {
+		this.db.close();
+	}
+
+	rawSqlite(): Database {
+		return this.db;
+	}
+
+	async sync(): Promise<void> {
+		// No-op for local-only mode
+	}
+}
+
+/**
+ * Create an in-memory BunSqliteDb instance (for testing).
+ */
+export function createMemoryDb(): BunSqliteDb {
+	return new BunSqliteDb(new Database(":memory:"));
+}
+
+// ---------------------------------------------------------------------------
+// LibSqlDb — embedded replica via @libsql/client
+// ---------------------------------------------------------------------------
+
+export class LibSqlDb implements SiaDb {
+	constructor(
+		private readonly client: {
+			execute: (...args: unknown[]) => Promise<{ rows?: unknown[] }>;
+			batch?: (...args: unknown[]) => Promise<unknown>;
+			sync?: () => Promise<void>;
+			close?: () => Promise<void>;
+		},
+	) {}
+
+	async execute(sql: string, params: unknown[] = []): Promise<{ rows: Record<string, unknown>[] }> {
+		const result = await this.client.execute({ sql, args: params as unknown[] });
+		const rows = Array.isArray(result?.rows)
+			? result.rows.map((row: unknown) => row as Record<string, unknown>)
+			: [];
+		return { rows };
+	}
+
+	async executeMany(statements: Array<{ sql: string; params?: unknown[] }>): Promise<void> {
+		if (typeof this.client.batch === "function") {
+			await this.client.batch(
+				statements.map(({ sql, params = [] }) => ({ sql, args: params as unknown[] })),
+				"write",
+			);
+			return;
+		}
+
+		for (const { sql, params = [] } of statements) {
+			await this.client.execute({ sql, args: params as unknown[] });
+		}
+	}
+
+	async transaction(fn: (db: SiaDb) => Promise<void>): Promise<void> {
+		const txProxy: SiaDb = {
+			execute: (sql, params) => this.execute(sql, params),
+			executeMany: (stmts) => this.executeMany(stmts),
+			transaction: async () => {
+				throw new Error("Nested transactions not supported");
+			},
+			close: async () => {},
+			rawSqlite: () => null,
+		};
+
+		await this.client.execute("BEGIN");
+		try {
+			await fn(txProxy);
+			await this.client.execute("COMMIT");
+		} catch (err) {
+			await this.client.execute("ROLLBACK");
+			throw err;
+		}
+	}
+
+	async close(): Promise<void> {
+		if (typeof this.client.close === "function") {
+			await this.client.close();
+		}
+	}
+
+	rawSqlite(): Database | null {
+		return null;
+	}
+
+	async sync(): Promise<void> {
+		if (typeof this.client.sync === "function") {
+			await this.client.sync();
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// openDb factory & openSiaDb router
+// ---------------------------------------------------------------------------
+
+/** Options for openDb / openSiaDb. */
+export interface OpenDbOpts {
+	readonly?: boolean;
+	/** Override SIA_HOME (useful for testing). */
+	siaHome?: string;
+}
+
+/**
+ * Open (or create) a bun:sqlite database at `{siaHome}/repos/{repoHash}/graph.db`.
+ * Sets WAL journal mode, NORMAL synchronous, and foreign_keys ON unless `readonly`.
+ */
+export function openDb(repoHash: string, opts: OpenDbOpts = {}): BunSqliteDb {
+	const home = opts.siaHome ?? SIA_HOME;
+	const dir = join(home, "repos", repoHash);
+	mkdirSync(dir, { recursive: true });
+
+	const dbPath = join(dir, "graph.db");
+	const db = new Database(dbPath, { readonly: opts.readonly ?? false });
+
+	if (!opts.readonly) {
+		(db as unknown as { pragma: (s: string) => void }).pragma("journal_mode = WAL");
+		(db as unknown as { pragma: (s: string) => void }).pragma("synchronous = NORMAL");
+		(db as unknown as { pragma: (s: string) => void }).pragma("foreign_keys = ON");
+	}
+
+	return new BunSqliteDb(db);
+}
+
+/**
+ * Open the appropriate SiaDb implementation based on SyncConfig.
+ *
+ * - sync disabled or no serverUrl  => local bun:sqlite via openDb
+ * - sync enabled + serverUrl       => dynamic import createSiaDb from @/sync/client
+ */
+export async function openSiaDb(
+	repoHash: string,
+	syncConfig: SyncConfig,
+	opts: OpenDbOpts = {},
+): Promise<SiaDb> {
+	if (!syncConfig.enabled || !syncConfig.serverUrl) {
+		return openDb(repoHash, opts);
+	}
+
+	// Dynamic import so that @/sync/client is only loaded when sync is actually used
+	const { createSiaDb } = await import("@/sync/client");
+	return createSiaDb(repoHash, syncConfig, opts);
+}

package/src/graph/edges.ts

@@ -0,0 +1,163 @@
+// Module: edges — Edge CRUD layer (bi-temporal, never hard-deletes)
+
+import { randomUUID } from "node:crypto";
+import { writeAuditEntry } from "@/graph/audit";
+import type { SiaDb } from "@/graph/db-interface";
+
+/** Shape accepted by insertEdge. Caller supplies classification and endpoints; we generate id & timestamps. */
+export interface NewEdge {
+	from_id: string;
+	to_id: string;
+	type: string;
+	weight?: number;
+	confidence?: number;
+	trust_tier?: number;
+	t_valid_from?: number | null;
+	source_episode?: string | null;
+	extraction_method?: string | null;
+}
+
+/** Row shape returned by edge queries. */
+export interface EdgeRow {
+	id: string;
+	from_id: string;
+	to_id: string;
+	type: string;
+	weight: number;
+	confidence: number;
+	trust_tier: number;
+	t_created: number;
+	t_expired: number | null;
+	t_valid_from: number | null;
+	t_valid_until: number | null;
+	hlc_created: number | null;
+	hlc_modified: number | null;
+	source_episode: string | null;
+	extraction_method: string | null;
+}
+
+/**
+ * Insert a new edge into the graph.
+ *
+ * Generates a UUID for `id`, sets `t_created = Date.now()`, `t_valid_until = null`.
+ * Writes an 'ADD' audit log entry.
+ */
+export async function insertEdge(db: SiaDb, edge: NewEdge): Promise<EdgeRow> {
+	const id = randomUUID();
+	const now = Date.now();
+
+	await db.execute(
+		`INSERT INTO graph_edges (
+			id, from_id, to_id, type, weight, confidence, trust_tier,
+			t_created, t_expired, t_valid_from, t_valid_until,
+			source_episode, extraction_method
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, NULL, ?, ?)`,
+		[
+			id,
+			edge.from_id,
+			edge.to_id,
+			edge.type,
+			edge.weight ?? 1.0,
+			edge.confidence ?? 0.7,
+			edge.trust_tier ?? 3,
+			now,
+			edge.t_valid_from ?? null,
+			edge.source_episode ?? null,
+			edge.extraction_method ?? null,
+		],
+	);
+
+	await writeAuditEntry(db, "ADD", { edge_id: id });
+
+	return {
+		id,
+		from_id: edge.from_id,
+		to_id: edge.to_id,
+		type: edge.type,
+		weight: edge.weight ?? 1.0,
+		confidence: edge.confidence ?? 0.7,
+		trust_tier: edge.trust_tier ?? 3,
+		t_created: now,
+		t_expired: null,
+		t_valid_from: edge.t_valid_from ?? null,
+		t_valid_until: null,
+		hlc_created: null,
+		hlc_modified: null,
+		source_episode: edge.source_episode ?? null,
+		extraction_method: edge.extraction_method ?? null,
+	};
+}
+
+/**
+ * Invalidate an edge (soft-delete).
+ *
+ * Sets BOTH `t_valid_until` AND `t_expired` to the given timestamp (default: now).
+ * Writes an 'INVALIDATE' audit log entry.
+ * Never hard-deletes.
+ */
+export async function invalidateEdge(db: SiaDb, id: string, tValidUntil?: number): Promise<void> {
+	const ts = tValidUntil ?? Date.now();
+
+	await db.execute("UPDATE graph_edges SET t_valid_until = ?, t_expired = ? WHERE id = ?", [
+		ts,
+		ts,
+		id,
+	]);
+
+	await writeAuditEntry(db, "INVALIDATE", { edge_id: id });
+}
+
+/**
+ * Get all currently active edges for an entity (as source or target).
+ *
+ * Active = `t_valid_until IS NULL`.
+ */
+export async function getActiveEdges(db: SiaDb, entityId: string): Promise<EdgeRow[]> {
+	const result = await db.execute(
+		`SELECT * FROM graph_edges
+		 WHERE (from_id = ? OR to_id = ?)
+		   AND t_valid_until IS NULL`,
+		[entityId, entityId],
+	);
+	return result.rows as unknown as EdgeRow[];
+}
+
+/**
+ * Get currently active edges from a source node filtered by type(s).
+ *
+ * Returns edges where `from_id = fromId`, `type IN types`, and `t_valid_until IS NULL`.
+ */
+export async function getEdgesByType(
+	db: SiaDb,
+	fromId: string,
+	types: string[],
+): Promise<Record<string, unknown>[]> {
+	const placeholders = types.map(() => "?").join(", ");
+	const { rows } = await db.execute(
+		`SELECT * FROM graph_edges WHERE from_id = ? AND type IN (${placeholders}) AND t_valid_until IS NULL`,
+		[fromId, ...types],
+	);
+	return rows;
+}
+
+/**
+ * Get edges for an entity that were valid at a specific point in time.
+ *
+ * Matches edges where:
+ * - `t_valid_from IS NULL OR t_valid_from <= asOfMs`  (edge had started)
+ * - `t_valid_until IS NULL OR t_valid_until > asOfMs`  (edge had not yet ended)
+ */
+export async function getEdgesAsOf(
+	db: SiaDb,
+	entityId: string,
+	asOfMs: number,
+): Promise<EdgeRow[]> {
+	const result = await db.execute(
+		`SELECT * FROM graph_edges
+		 WHERE (from_id = ? OR to_id = ?)
+		   AND (t_valid_from IS NULL OR t_valid_from <= ?)
+		   AND (t_valid_until IS NULL OR t_valid_until > ?)`,
+		[entityId, entityId, asOfMs, asOfMs],
+	);
+	return result.rows as unknown as EdgeRow[];
+}