@rkarim08/sia 1.0.0

package/src/graph/entities.ts

@@ -0,0 +1,327 @@
+// Module: entities — Entity CRUD layer with bi-temporal invalidation
+
+import { v4 as uuid } from "uuid";
+import { writeAuditEntry } from "@/graph/audit";
+import type { SiaDb } from "@/graph/db-interface";
+
+/** Shape of an entity row as stored in the database. */
+export interface Entity {
+	id: string;
+	type: string;
+	name: string;
+	content: string;
+	summary: string;
+	package_path: string | null;
+	tags: string;
+	file_paths: string;
+	trust_tier: number;
+	confidence: number;
+	base_confidence: number;
+	importance: number;
+	base_importance: number;
+	access_count: number;
+	edge_count: number;
+	last_accessed: number;
+	created_at: number;
+	t_created: number;
+	t_expired: number | null;
+	t_valid_from: number | null;
+	t_valid_until: number | null;
+	visibility: string;
+	created_by: string;
+	workspace_scope: string | null;
+	hlc_created: number | null;
+	hlc_modified: number | null;
+	synced_at: number | null;
+	conflict_group_id: string | null;
+	source_episode: string | null;
+	extraction_method: string | null;
+	extraction_model: string | null;
+	embedding: Uint8Array | null;
+	archived_at: number | null;
+	session_id: string | null;
+	kind: string | null;
+}
+
+/** Fields the caller must or may provide when inserting an entity. */
+export interface InsertEntityInput {
+	type: string;
+	name: string;
+	content: string;
+	summary: string;
+	package_path?: string | null;
+	tags?: string;
+	file_paths?: string;
+	trust_tier?: number;
+	confidence?: number;
+	base_confidence?: number;
+	importance?: number;
+	base_importance?: number;
+	access_count?: number;
+	edge_count?: number;
+	last_accessed?: number;
+	created_at?: number;
+	t_valid_from?: number | null;
+	visibility?: string;
+	created_by?: string;
+	workspace_scope?: string | null;
+	hlc_created?: number | null;
+	hlc_modified?: number | null;
+	source_episode?: string | null;
+	extraction_method?: string | null;
+	extraction_model?: string | null;
+	embedding?: Uint8Array | null;
+	session_id?: string | null;
+	kind?: string | null;
+}
+
+/** Fields that can be partially updated on an existing entity. */
+export type UpdateEntityInput = Partial<Omit<Entity, "id" | "t_created" | "created_at">>;
+
+/** Options for getActiveEntities. */
+export interface GetActiveEntitiesOpts {
+	limit?: number;
+}
+
+/**
+ * Insert a new entity into the graph database.
+ * Generates a UUID, sets t_created=now, t_valid_from as provided (default null),
+ * t_valid_until=null. Writes an ADD entry to the audit log.
+ */
+export async function insertEntity(db: SiaDb, input: InsertEntityInput): Promise<Entity> {
+	const now = Date.now();
+	const id = uuid();
+
+	const entity: Entity = {
+		id,
+		type: input.type,
+		name: input.name,
+		content: input.content,
+		summary: input.summary,
+		package_path: input.package_path ?? null,
+		tags: input.tags ?? "[]",
+		file_paths: input.file_paths ?? "[]",
+		trust_tier: input.trust_tier ?? 3,
+		confidence: input.confidence ?? 0.7,
+		base_confidence: input.base_confidence ?? 0.7,
+		importance: input.importance ?? 0.5,
+		base_importance: input.base_importance ?? 0.5,
+		access_count: input.access_count ?? 0,
+		edge_count: input.edge_count ?? 0,
+		last_accessed: input.last_accessed ?? now,
+		created_at: input.created_at ?? now,
+		t_created: now,
+		t_expired: null,
+		t_valid_from: input.t_valid_from ?? null,
+		t_valid_until: null,
+		visibility: input.visibility ?? "private",
+		created_by: input.created_by ?? "local",
+		workspace_scope: input.workspace_scope ?? null,
+		hlc_created: input.hlc_created ?? null,
+		hlc_modified: input.hlc_modified ?? null,
+		synced_at: null,
+		conflict_group_id: null,
+		source_episode: input.source_episode ?? null,
+		extraction_method: input.extraction_method ?? null,
+		extraction_model: input.extraction_model ?? null,
+		embedding: input.embedding ?? null,
+		archived_at: null,
+		session_id: input.session_id ?? null,
+		kind: input.kind ?? input.type,
+	};
+
+	await db.execute(
+		`INSERT INTO graph_nodes (
+			id, type, name, content, summary,
+			package_path, tags, file_paths,
+			trust_tier, confidence, base_confidence,
+			importance, base_importance,
+			access_count, edge_count,
+			last_accessed, created_at,
+			t_created, t_expired, t_valid_from, t_valid_until,
+			visibility, created_by, workspace_scope,
+			hlc_created, hlc_modified, synced_at,
+			conflict_group_id,
+			source_episode, extraction_method, extraction_model,
+			embedding, archived_at,
+			session_id, kind
+		) VALUES (
+			?, ?, ?, ?, ?,
+			?, ?, ?,
+			?, ?, ?,
+			?, ?,
+			?, ?,
+			?, ?,
+			?, ?, ?, ?,
+			?, ?, ?,
+			?, ?, ?,
+			?,
+			?, ?, ?,
+			?, ?,
+			?, ?
+		)`,
+		[
+			entity.id,
+			entity.type,
+			entity.name,
+			entity.content,
+			entity.summary,
+			entity.package_path,
+			entity.tags,
+			entity.file_paths,
+			entity.trust_tier,
+			entity.confidence,
+			entity.base_confidence,
+			entity.importance,
+			entity.base_importance,
+			entity.access_count,
+			entity.edge_count,
+			entity.last_accessed,
+			entity.created_at,
+			entity.t_created,
+			entity.t_expired,
+			entity.t_valid_from,
+			entity.t_valid_until,
+			entity.visibility,
+			entity.created_by,
+			entity.workspace_scope,
+			entity.hlc_created,
+			entity.hlc_modified,
+			entity.synced_at,
+			entity.conflict_group_id,
+			entity.source_episode,
+			entity.extraction_method,
+			entity.extraction_model,
+			entity.embedding,
+			entity.archived_at,
+			entity.session_id,
+			entity.kind,
+		],
+	);
+
+	await writeAuditEntry(db, "ADD", { entity_id: id });
+
+	return entity;
+}
+
+/**
+ * Retrieve a single entity by id.
+ * Returns the entity or undefined if not found.
+ */
+export async function getEntity(db: SiaDb, id: string): Promise<Entity | undefined> {
+	const result = await db.execute("SELECT * FROM graph_nodes WHERE id = ?", [id]);
+	return (result.rows[0] as unknown as Entity | undefined) ?? undefined;
+}
+
+/**
+ * Update partial fields on an existing entity.
+ * Writes an UPDATE entry to the audit log.
+ */
+export async function updateEntity(
+	db: SiaDb,
+	id: string,
+	updates: UpdateEntityInput,
+): Promise<void> {
+	const entries = Object.entries(updates).filter(([, v]) => v !== undefined);
+	if (entries.length === 0) return;
+
+	const setClauses = entries.map(([key]) => `${key} = ?`).join(", ");
+	const values = entries.map(([, v]) => v);
+
+	await db.execute(`UPDATE graph_nodes SET ${setClauses} WHERE id = ?`, [...values, id]);
+
+	await writeAuditEntry(db, "UPDATE", { entity_id: id });
+}
+
+/**
+ * Touch an entity: update last_accessed to now and increment access_count.
+ */
+export async function touchEntity(db: SiaDb, id: string): Promise<void> {
+	await db.execute(
+		"UPDATE graph_nodes SET last_accessed = ?, access_count = access_count + 1 WHERE id = ?",
+		[Date.now(), id],
+	);
+}
+
+/**
+ * Invalidate an entity (bi-temporal): sets both t_valid_until AND t_expired.
+ * Used when a fact is superseded or proven wrong.
+ * Does NOT set archived_at.
+ */
+export async function invalidateEntity(db: SiaDb, id: string, tValidUntil?: number): Promise<void> {
+	const ts = tValidUntil ?? Date.now();
+	await db.execute("UPDATE graph_nodes SET t_valid_until = ?, t_expired = ? WHERE id = ?", [
+		ts,
+		ts,
+		id,
+	]);
+
+	await writeAuditEntry(db, "INVALIDATE", { entity_id: id });
+}
+
+/**
+ * Archive an entity (soft delete for decayed/irrelevant entities).
+ * Sets archived_at only. Does NOT touch t_valid_until or t_expired.
+ */
+export async function archiveEntity(db: SiaDb, id: string): Promise<void> {
+	await db.execute("UPDATE graph_nodes SET archived_at = ? WHERE id = ?", [Date.now(), id]);
+
+	await writeAuditEntry(db, "ARCHIVE", { entity_id: id });
+}
+
+/**
+ * Retrieve active entities: those that are neither invalidated nor archived.
+ * Filters WHERE t_valid_until IS NULL AND archived_at IS NULL.
+ */
+export async function getActiveEntities(
+	db: SiaDb,
+	opts?: GetActiveEntitiesOpts,
+): Promise<Entity[]> {
+	const limit = opts?.limit;
+	const sql = limit
+		? "SELECT * FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL LIMIT ?"
+		: "SELECT * FROM graph_nodes WHERE t_valid_until IS NULL AND archived_at IS NULL";
+	const params = limit ? [limit] : [];
+
+	const result = await db.execute(sql, params);
+	return result.rows as unknown as Entity[];
+}
+
+/**
+ * Retrieve active entities scoped to a specific package path.
+ * Filters WHERE package_path = ? AND t_valid_until IS NULL AND archived_at IS NULL.
+ */
+export async function getEntitiesByPackage(db: SiaDb, packagePath: string): Promise<Entity[]> {
+	const result = await db.execute(
+		"SELECT * FROM graph_nodes WHERE package_path = ? AND t_valid_until IS NULL AND archived_at IS NULL",
+		[packagePath],
+	);
+	return result.rows as unknown as Entity[];
+}
+
+/**
+ * Retrieve active nodes belonging to a specific session.
+ * Filters WHERE session_id = ? AND archived_at IS NULL AND t_valid_until IS NULL.
+ */
+export async function getNodesBySession(
+	db: SiaDb,
+	sessionId: string,
+): Promise<Record<string, unknown>[]> {
+	const { rows } = await db.execute(
+		"SELECT * FROM graph_nodes WHERE session_id = ? AND archived_at IS NULL AND t_valid_until IS NULL",
+		[sessionId],
+	);
+	return rows;
+}
+
+/**
+ * Retrieve active nodes of a specific semantic kind.
+ * Filters WHERE kind = ? AND archived_at IS NULL AND t_valid_until IS NULL.
+ */
+export async function getNodesByKind(db: SiaDb, kind: string): Promise<Record<string, unknown>[]> {
+	const { rows } = await db.execute(
+		"SELECT * FROM graph_nodes WHERE kind = ? AND archived_at IS NULL AND t_valid_until IS NULL",
+		[kind],
+	);
+	return rows;
+}

package/src/graph/episodic-db.ts

@@ -0,0 +1,113 @@
+// Module: episodic-db — Episode CRUD and session tracking
+
+import { v4 as uuid } from "uuid";
+import type { SiaDb } from "@/graph/db-interface";
+import type { Episode, InsertEpisodeInput } from "@/graph/types";
+
+// Re-export the opener (canonical source: semantic-db.ts)
+export { openEpisodicDb } from "@/graph/semantic-db";
+
+/**
+ * Insert a new episode into the episodic database.
+ * Generates a UUID and sets ts=Date.now().
+ */
+export async function insertEpisode(db: SiaDb, input: InsertEpisodeInput): Promise<Episode> {
+	const id = uuid();
+	const ts = Date.now();
+
+	const episode: Episode = {
+		id,
+		session_id: input.session_id,
+		ts,
+		type: input.type,
+		role: input.role ?? null,
+		content: input.content,
+		tool_name: input.tool_name ?? null,
+		file_path: input.file_path ?? null,
+		trust_tier: input.trust_tier ?? 3,
+	};
+
+	await db.execute(
+		`INSERT INTO episodes (id, session_id, ts, type, role, content, tool_name, file_path, trust_tier)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		[
+			episode.id,
+			episode.session_id,
+			episode.ts,
+			episode.type,
+			episode.role,
+			episode.content,
+			episode.tool_name,
+			episode.file_path,
+			episode.trust_tier,
+		],
+	);
+
+	return episode;
+}
+
+/**
+ * Retrieve all episodes for a given session, ordered by ts ASC.
+ */
+export async function getEpisodesBySession(db: SiaDb, sessionId: string): Promise<Episode[]> {
+	const result = await db.execute(
+		"SELECT id, session_id, ts, type, role, content, tool_name, file_path, trust_tier FROM episodes WHERE session_id = ? ORDER BY ts ASC",
+		[sessionId],
+	);
+	return result.rows as unknown as Episode[];
+}
+
+/**
+ * Retrieve the most recent episodes across all sessions, ordered by ts DESC.
+ * Defaults to a limit of 20.
+ */
+export async function getRecentEpisodes(db: SiaDb, limit = 20): Promise<Episode[]> {
+	const result = await db.execute(
+		"SELECT id, session_id, ts, type, role, content, tool_name, file_path, trust_tier FROM episodes ORDER BY ts DESC LIMIT ?",
+		[limit],
+	);
+	return result.rows as unknown as Episode[];
+}
+
+/**
+ * Mark a session as processed in sessions_processed.
+ * Uses an UPSERT so calling this multiple times updates the record.
+ * Defaults pipeline_version to "1.0.0" if not provided.
+ */
+export async function markSessionProcessed(
+	db: SiaDb,
+	sessionId: string,
+	status: "complete" | "partial" | "failed",
+	entityCount: number,
+	pipelineVersion?: string,
+): Promise<void> {
+	const processedAt = Date.now();
+	const version = pipelineVersion ?? "1.0.0";
+
+	await db.execute(
+		`INSERT INTO sessions_processed (session_id, processing_status, processed_at, entity_count, pipeline_version)
+		 VALUES (?, ?, ?, ?, ?)
+		 ON CONFLICT(session_id) DO UPDATE SET
+		   processing_status = excluded.processing_status,
+		   processed_at = excluded.processed_at,
+		   entity_count = excluded.entity_count,
+		   pipeline_version = excluded.pipeline_version`,
+		[sessionId, status, processedAt, entityCount, version],
+	);
+}
+
+/**
+ * Return session IDs that have not been successfully processed.
+ * Includes sessions that have never been processed (no entry in sessions_processed)
+ * and sessions whose processing_status is 'failed'.
+ */
+export async function getUnprocessedSessions(db: SiaDb): Promise<string[]> {
+	const result = await db.execute(
+		`SELECT DISTINCT e.session_id
+		 FROM episodes e
+		 LEFT JOIN sessions_processed sp ON sp.session_id = e.session_id
+		 WHERE sp.session_id IS NULL OR sp.processing_status = 'failed'`,
+		[],
+	);
+	return (result.rows as Array<{ session_id: string }>).map((r) => r.session_id);
+}

package/src/graph/flags.ts

@@ -0,0 +1,31 @@
+// Module: flags — Session flag CRUD operations
+
+import type { SiaDb } from "@/graph/db-interface";
+
+/** A session flag row from the session_flags table. */
+export interface SessionFlag {
+	id: string;
+	session_id: string;
+	reason: string;
+	transcript_position: number | null;
+	created_at: number;
+	consumed: number;
+}
+
+/**
+ * Retrieve all unconsumed flags for a given session, ordered by creation time.
+ */
+export async function getUnconsumedFlags(db: SiaDb, sessionId: string): Promise<SessionFlag[]> {
+	const result = await db.execute(
+		"SELECT id, session_id, reason, transcript_position, created_at, consumed FROM session_flags WHERE session_id = ? AND consumed = 0 ORDER BY created_at",
+		[sessionId],
+	);
+	return result.rows as unknown as SessionFlag[];
+}
+
+/**
+ * Mark a single flag as consumed so it is not returned by getUnconsumedFlags.
+ */
+export async function markFlagConsumed(db: SiaDb, flagId: string): Promise<void> {
+	await db.execute("UPDATE session_flags SET consumed = 1 WHERE id = ?", [flagId]);
+}

package/src/graph/meta-db.ts

@@ -0,0 +1,200 @@
+// Module: meta-db — Meta database opener and workspace/repo registry CRUD
+
+import { createHash, randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import type { BunSqliteDb, SiaDb } from "@/graph/db-interface";
+import { runMigrations } from "@/graph/semantic-db";
+import { SIA_HOME } from "@/shared/config";
+
+/**
+ * Open (or create) the global meta database.
+ * Resolves to `{siaHome}/meta.db` (not under repos/) and applies
+ * migrations from the `migrations/meta` directory.
+ */
+export function openMetaDb(siaHome?: string): BunSqliteDb {
+	const home = siaHome ?? SIA_HOME;
+	const dbPath = join(home, "meta.db");
+	const migrationsDir = resolve(import.meta.dirname, "../../migrations/meta");
+	return runMigrations(dbPath, migrationsDir);
+}
+
+// ---------------------------------------------------------------------------
+// Repo registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a repository by its absolute path.
+ * Computes a SHA-256 hash of the resolved path as the repo id.
+ * Idempotent — if the repo already exists, updates `last_accessed`.
+ * Returns the repo id (the hash).
+ */
+export async function registerRepo(db: SiaDb, path: string): Promise<string> {
+	const resolved = resolve(path);
+	const id = createHash("sha256").update(resolved).digest("hex");
+	const now = Date.now();
+
+	await db.execute(
+		`INSERT INTO repos (id, path, created_at, last_accessed)
+		 VALUES (?, ?, ?, ?)
+		 ON CONFLICT(id) DO UPDATE SET last_accessed = ?`,
+		[id, resolved, now, now, now],
+	);
+
+	return id;
+}
+
+/**
+ * Look up a repo by its absolute path.
+ * Hashes the path and returns the row, or null if not found.
+ */
+export async function getRepoByPath(
+	db: SiaDb,
+	path: string,
+): Promise<Record<string, unknown> | null> {
+	const resolved = resolve(path);
+	const id = createHash("sha256").update(resolved).digest("hex");
+
+	const result = await db.execute("SELECT * FROM repos WHERE id = ?", [id]);
+	return result.rows[0] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace CRUD
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new workspace with the given name.
+ * Generates a UUID v4 as the workspace id. Returns the id.
+ */
+export async function createWorkspace(db: SiaDb, name: string): Promise<string> {
+	const id = randomUUID();
+	const now = Date.now();
+
+	await db.execute("INSERT INTO workspaces (id, name, created_at) VALUES (?, ?, ?)", [
+		id,
+		name,
+		now,
+	]);
+
+	return id;
+}
+
+/**
+ * Resolve a workspace name to its UUID.
+ * Returns the id if found, or null if no workspace with that name exists.
+ */
+export async function resolveWorkspaceName(db: SiaDb, name: string): Promise<string | null> {
+	const result = await db.execute("SELECT id FROM workspaces WHERE name = ?", [name]);
+	if (result.rows.length === 0) return null;
+	return result.rows[0]?.id as string;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace-repo associations
+// ---------------------------------------------------------------------------
+
+/**
+ * Add a repo to a workspace (workspace_repos join table).
+ */
+export async function addRepoToWorkspace(
+	db: SiaDb,
+	workspaceId: string,
+	repoId: string,
+): Promise<void> {
+	await db.execute("INSERT INTO workspace_repos (workspace_id, repo_id) VALUES (?, ?)", [
+		workspaceId,
+		repoId,
+	]);
+}
+
+/**
+ * Remove a repo from a workspace.
+ */
+export async function removeRepoFromWorkspace(
+	db: SiaDb,
+	workspaceId: string,
+	repoId: string,
+): Promise<void> {
+	await db.execute("DELETE FROM workspace_repos WHERE workspace_id = ? AND repo_id = ?", [
+		workspaceId,
+		repoId,
+	]);
+}
+
+/**
+ * Get all repos belonging to a workspace (joined with the repos table).
+ */
+export async function getWorkspaceRepos(
+	db: SiaDb,
+	workspaceId: string,
+): Promise<Record<string, unknown>[]> {
+	const result = await db.execute(
+		`SELECT r.*, wr.role
+		 FROM repos r
+		 INNER JOIN workspace_repos wr ON wr.repo_id = r.id
+		 WHERE wr.workspace_id = ?`,
+		[workspaceId],
+	);
+	return result.rows;
+}
+
+// ---------------------------------------------------------------------------
+// Workspace listing
+// ---------------------------------------------------------------------------
+
+/** Row shape returned by listWorkspaces. */
+export interface WorkspaceListItem {
+	id: string;
+	name: string;
+	created_at: number;
+	member_count: number;
+}
+
+/**
+ * List all workspaces with their member counts.
+ */
+export async function listWorkspaces(db: SiaDb): Promise<WorkspaceListItem[]> {
+	const result = await db.execute(
+		`SELECT w.id, w.name, w.created_at,
+		        COUNT(wr.repo_id) as member_count
+		 FROM workspaces w
+		 LEFT JOIN workspace_repos wr ON wr.workspace_id = w.id
+		 GROUP BY w.id
+		 ORDER BY w.name`,
+	);
+	return result.rows as unknown as WorkspaceListItem[];
+}
+
+/**
+ * Get the count of api_contracts for repos in a workspace.
+ */
+export async function getWorkspaceContractCount(db: SiaDb, workspaceId: string): Promise<number> {
+	const result = await db.execute(
+		`SELECT COUNT(*) as cnt FROM api_contracts ac
+		 WHERE ac.provider_repo_id IN (
+		   SELECT repo_id FROM workspace_repos WHERE workspace_id = ?
+		 )`,
+		[workspaceId],
+	);
+	return (result.rows[0]?.cnt as number) ?? 0;
+}
+
+// ---------------------------------------------------------------------------
+// Sharing rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Get sharing rules for a workspace.
+ * Returns rules that match the given workspace_id OR have a NULL workspace_id
+ * (global rules that apply to all workspaces).
+ */
+export async function getSharingRules(
+	db: SiaDb,
+	workspaceId: string,
+): Promise<Record<string, unknown>[]> {
+	const result = await db.execute(
+		"SELECT * FROM sharing_rules WHERE workspace_id = ? OR workspace_id IS NULL",
+		[workspaceId],
+	);
+	return result.rows;
+}