@rkarim08/sia 1.0.0

package/src/shared/llm-client.ts

@@ -0,0 +1,120 @@
+// Module: llm-client — Shared LLM client with Anthropic SDK + air-gapped fallback
+import type { SiaConfig } from "@/shared/config";
+
+/** LLM client interface for summarization and classification tasks. */
+export interface LlmClient {
+	summarize(prompt: string): Promise<string>;
+	classify(prompt: string, options: string[]): Promise<string>;
+}
+
+/** Rate limiter state */
+interface RateLimiter {
+	tokens: number;
+	maxTokens: number;
+	refillRate: number; // tokens per ms
+	lastRefill: number;
+}
+
+function createRateLimiter(maxPerMinute: number): RateLimiter {
+	return {
+		tokens: maxPerMinute,
+		maxTokens: maxPerMinute,
+		refillRate: maxPerMinute / 60000,
+		lastRefill: Date.now(),
+	};
+}
+
+async function acquireToken(limiter: RateLimiter): Promise<void> {
+	const now = Date.now();
+	const elapsed = now - limiter.lastRefill;
+	limiter.tokens = Math.min(limiter.maxTokens, limiter.tokens + elapsed * limiter.refillRate);
+	limiter.lastRefill = now;
+
+	if (limiter.tokens < 1) {
+		const waitMs = (1 - limiter.tokens) / limiter.refillRate;
+		await new Promise((r) => setTimeout(r, waitMs));
+		limiter.tokens = 0;
+	} else {
+		limiter.tokens -= 1;
+	}
+}
+
+/** Air-gapped/fallback client that uses heuristic string concatenation. */
+export function createFallbackClient(): LlmClient {
+	return {
+		async summarize(prompt: string): Promise<string> {
+			const lines = prompt.split("\n").filter((l) => l.trim().length > 0);
+			return lines.slice(0, 5).join("; ").slice(0, 500);
+		},
+		async classify(_prompt: string, options: string[]): Promise<string> {
+			return options[0] ?? "unknown";
+		},
+	};
+}
+
+/** Create an LLM client backed by the Anthropic SDK with rate limiting. */
+export function createLlmClient(config: SiaConfig): LlmClient {
+	// Air-gapped mode or no API key → fallback
+	const apiKey = process.env.ANTHROPIC_API_KEY;
+	if (config.airGapped || !apiKey) {
+		return createFallbackClient();
+	}
+
+	const model = config.captureModel ?? "claude-haiku-4-5-20251001";
+	const limiter = createRateLimiter(10);
+	let anthropicClient: {
+		messages: {
+			create: (opts: Record<string, unknown>) => Promise<{ content: Array<{ text?: string }> }>;
+		};
+	} | null = null;
+
+	async function getClient() {
+		if (!anthropicClient) {
+			const { default: Anthropic } = await import("@anthropic-ai/sdk");
+			anthropicClient = new Anthropic({ apiKey }) as unknown as typeof anthropicClient;
+		}
+		// biome-ignore lint/style/noNonNullAssertion: assigned above
+		return anthropicClient!;
+	}
+
+	return {
+		async summarize(prompt: string): Promise<string> {
+			try {
+				await acquireToken(limiter);
+				const client = await getClient();
+				const response = await client.messages.create({
+					model,
+					max_tokens: 300,
+					messages: [{ role: "user", content: prompt }],
+				});
+				const text = response.content[0]?.text;
+				return text ?? createFallbackClient().summarize(prompt);
+			} catch (err) {
+				console.warn("LLM summarize failed, using fallback:", err);
+				return createFallbackClient().summarize(prompt);
+			}
+		},
+		async classify(prompt: string, options: string[]): Promise<string> {
+			try {
+				await acquireToken(limiter);
+				const client = await getClient();
+				const response = await client.messages.create({
+					model,
+					max_tokens: 50,
+					messages: [
+						{
+							role: "user",
+							content: `${prompt}\n\nRespond with exactly one of: ${options.join(", ")}`,
+						},
+					],
+				});
+				const text = (response.content[0]?.text ?? "").trim().toLowerCase();
+				const match = options.find((o) => text.includes(o.toLowerCase()));
+				return match ?? options[0] ?? "unknown";
+			} catch (err) {
+				console.warn("LLM classify failed, using fallback:", err);
+				return options[0] ?? "unknown";
+			}
+		},
+	};
+}

package/src/shared/logger.ts

@@ -0,0 +1,99 @@
+// Module: logger — structured JSON logging to sia.log
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { SIA_HOME } from "@/shared/config";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogEntry {
+	ts: number;
+	level: LogLevel;
+	module: string;
+	op: string;
+	message: string;
+	error?: string;
+	[key: string]: unknown;
+}
+
+export interface Logger {
+	debug(module: string, op: string, message: string, extra?: Record<string, unknown>): void;
+	info(module: string, op: string, message: string, extra?: Record<string, unknown>): void;
+	warn(module: string, op: string, message: string, extra?: Record<string, unknown>): void;
+	error(
+		module: string,
+		op: string,
+		message: string,
+		err?: unknown,
+		extra?: Record<string, unknown>,
+	): void;
+}
+
+export function createLogger(siaHome?: string): Logger {
+	const home = siaHome ?? SIA_HOME;
+	const logDir = join(home, "logs");
+	const logFile = join(logDir, "sia.log");
+
+	if (!existsSync(logDir)) {
+		mkdirSync(logDir, { recursive: true });
+	}
+
+	function write(entry: LogEntry): void {
+		appendFileSync(logFile, `${JSON.stringify(entry)}\n`);
+	}
+
+	function log(
+		level: LogLevel,
+		module: string,
+		op: string,
+		message: string,
+		extra?: Record<string, unknown>,
+	): void {
+		const entry: LogEntry = {
+			ts: Date.now(),
+			level,
+			module,
+			op,
+			message,
+			...extra,
+		};
+		write(entry);
+	}
+
+	return {
+		debug(module: string, op: string, message: string, extra?: Record<string, unknown>): void {
+			log("debug", module, op, message, extra);
+		},
+
+		info(module: string, op: string, message: string, extra?: Record<string, unknown>): void {
+			log("info", module, op, message, extra);
+		},
+
+		warn(module: string, op: string, message: string, extra?: Record<string, unknown>): void {
+			log("warn", module, op, message, extra);
+		},
+
+		error(
+			module: string,
+			op: string,
+			message: string,
+			err?: unknown,
+			extra?: Record<string, unknown>,
+		): void {
+			const errorMessage =
+				err instanceof Error ? err.message : err != null ? String(err) : undefined;
+			const entry: LogEntry = {
+				ts: Date.now(),
+				level: "error",
+				module,
+				op,
+				message,
+				...(errorMessage != null ? { error: errorMessage } : {}),
+				...extra,
+			};
+			write(entry);
+		},
+	};
+}
+
+export const defaultLogger: Logger = createLogger();

package/src/shared/types.ts

@@ -0,0 +1,79 @@
+// src/shared/types.ts — Cross-module type aliases
+// No runtime code. No imports from other Sia modules (prevents circular deps).
+
+// ── Semantic aliases ──────────────────────────────────────────
+export type UnixMs = number;
+export type RepoHash = string;
+export type PackagePath = string | null;
+export type NodeId = string;
+export type EdgeId = string;
+export type SessionId = string;
+
+// ── Trust ─────────────────────────────────────────────────────
+export type TrustTier = 1 | 2 | 3 | 4;
+
+// ── Operations ────────────────────────────────────────────────
+// Re-exported from capture/types.ts to provide a single shared import path.
+export type { ConsolidationOp } from "@/capture/types";
+export type ValidationStatus = "pending" | "passed" | "rejected" | "quarantined";
+export type ProcessingStatus = "complete" | "partial" | "failed";
+export type Visibility = "private" | "team" | "project";
+
+// ── Current entity types ──────────────────────────────────────
+// Re-exported from capture/types.ts to avoid duplication.
+export type { EntityType } from "@/capture/types";
+
+// ── Forward-looking node kinds (Phase 14+ unified graph_nodes schema) ──
+// Current code should use EntityType above. These are for future phases.
+export type StructuralKind = "CodeSymbol" | "FileNode" | "PackageNode";
+export type SemanticKind =
+	| "Concept"
+	| "Decision"
+	| "Bug"
+	| "Solution"
+	| "Convention"
+	| "Community"
+	| "ContentChunk";
+export type EventKind =
+	| "SessionNode"
+	| "EditEvent"
+	| "ExecutionEvent"
+	| "SearchEvent"
+	| "GitEvent"
+	| "ErrorEvent"
+	| "UserDecision"
+	| "UserPrompt"
+	| "TaskNode";
+export type NodeKind = StructuralKind | SemanticKind | EventKind | "ExternalRef";
+
+// ── Edge types (current schema) ───────────────────────────────
+export type StructuralEdgeType =
+	| "defines"
+	| "imports"
+	| "calls"
+	| "inherits_from"
+	| "contains"
+	| "depends_on";
+export type SemanticEdgeType =
+	| "pertains_to"
+	| "solves"
+	| "caused_by"
+	| "supersedes"
+	| "elaborates"
+	| "contradicts"
+	| "relates_to"
+	| "references";
+export type CommunityEdgeType = "member_of" | "summarized_by";
+export type EdgeType = StructuralEdgeType | SemanticEdgeType | CommunityEdgeType;
+
+// ── Forward-looking edge types (Phase 14+) ────────────────────
+export type EventEdgeType =
+	| "modifies"
+	| "triggered_by"
+	| "produced_by"
+	| "resolves"
+	| "during_task"
+	| "precedes";
+export type SessionEdgeType = "part_of" | "continued_from";
+export type DocEdgeType = "child_of";
+export type AllEdgeType = EdgeType | EventEdgeType | SessionEdgeType | DocEdgeType;

package/src/sync/client.ts

@@ -0,0 +1,43 @@
+// Module: client — LibSQL-backed SiaDb factory for team sync
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { OpenDbOpts, SiaDb } from "@/graph/db-interface";
+import { LibSqlDb } from "@/graph/db-interface";
+import type { SyncConfig } from "@/shared/config";
+import { SIA_HOME } from "@/shared/config";
+import { getToken } from "@/sync/keychain";
+
+/**
+ * Open a LibSqlDb (embedded replica) when sync is enabled; otherwise fall back
+ * to the local BunSqliteDb.
+ */
+export async function createSiaDb(
+	repoHash: string,
+	config: SyncConfig,
+	opts: OpenDbOpts = {},
+): Promise<SiaDb> {
+	if (!config.enabled || !config.serverUrl) {
+		throw new Error("createSiaDb() called without sync enabled. Use openSiaDb() instead.");
+	}
+
+	const token = await getToken(config.serverUrl);
+	if (!token) {
+		throw new Error("Run 'npx sia team join' to authenticate");
+	}
+
+	const home = opts.siaHome ?? SIA_HOME;
+	const repoDir = join(home, "repos", repoHash);
+	mkdirSync(repoDir, { recursive: true });
+	const dbPath = join(repoDir, "graph.db");
+
+	const { createClient } = await import("@libsql/client");
+	const client = createClient({
+		url: `file:${dbPath}`,
+		syncUrl: config.serverUrl,
+		authToken: token,
+		syncInterval: config.syncInterval,
+	});
+
+	return new LibSqlDb(client as unknown as ConstructorParameters<typeof LibSqlDb>[0]);
+}

package/src/sync/conflict.ts

@@ -0,0 +1,106 @@
+// Module: conflict — conflict detection for concurrent facts
+
+import { v4 as uuid } from "uuid";
+import { wordJaccard } from "@/capture/consolidate";
+import type { SiaDb } from "@/graph/db-interface";
+import type { Entity } from "@/graph/entities";
+import type { LlmClient } from "@/shared/llm-client";
+import { cosineSimilarity } from "@/sync/dedup";
+
+/**
+ * Compute the magnitude (L2 norm) of an embedding vector.
+ */
+function embeddingMagnitude(e: Uint8Array | null): number | null {
+	if (!e) return null;
+	const f = new Float32Array(e.buffer, e.byteOffset, Math.floor(e.byteLength / 4));
+	if (f.length === 0) return null;
+	let sum = 0;
+	for (let i = 0; i < f.length; i++) {
+		sum += f[i] * f[i];
+	}
+	return Math.sqrt(sum);
+}
+
+function rangesOverlap(
+	aStart: number | null,
+	aEnd: number | null,
+	bStart: number | null,
+	bEnd: number | null,
+): boolean {
+	const a0 = aStart ?? Number.MIN_SAFE_INTEGER;
+	const a1 = aEnd ?? Number.MAX_SAFE_INTEGER;
+	const b0 = bStart ?? Number.MIN_SAFE_INTEGER;
+	const b1 = bEnd ?? Number.MAX_SAFE_INTEGER;
+	return a0 <= b1 && b0 <= a1;
+}
+
+export async function detectConflicts(db: SiaDb, llmClient?: LlmClient): Promise<number> {
+	const result = await db.execute(
+		"SELECT * FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL",
+	);
+	const entities = result.rows as unknown as Entity[];
+
+	let conflicts = 0;
+
+	for (let i = 0; i < entities.length; i++) {
+		for (let j = i + 1; j < entities.length; j++) {
+			const a = entities[i];
+			const b = entities[j];
+
+			if (a.type !== b.type) continue;
+			if (!rangesOverlap(a.t_valid_from, a.t_valid_until, b.t_valid_from, b.t_valid_until))
+				continue;
+
+			// Pre-filter: skip pairs where embedding magnitude difference > 0.3
+			const magA = embeddingMagnitude(a.embedding);
+			const magB = embeddingMagnitude(b.embedding);
+			if (magA !== null && magB !== null && Math.abs(magA - magB) > 0.3) continue;
+
+			// Similarity check: cosine for entities with embeddings, wordJaccard fallback
+			let similar = false;
+			const bothHaveEmbeddings = a.embedding !== null && b.embedding !== null;
+			if (bothHaveEmbeddings) {
+				const cosine = cosineSimilarity(a.embedding, b.embedding);
+				similar = cosine !== null && cosine > 0.85;
+			} else {
+				const jaccard = wordJaccard(a.content, b.content);
+				similar = jaccard > 0.95;
+			}
+
+			if (!similar) continue;
+
+			// Contradiction check: LLM classification or content comparison fallback
+			let contradictory: boolean;
+			if (llmClient) {
+				const prompt = `Fact A: "${a.name}" — ${a.content}\nFact B: "${b.name}" — ${b.content}\n\nAre these two facts contradictory, complementary, or duplicate?`;
+				const classification = await llmClient.classify(prompt, [
+					"contradictory",
+					"complementary",
+					"duplicate",
+				]);
+				contradictory = classification === "contradictory";
+			} else {
+				contradictory = a.content !== b.content;
+			}
+
+			if (contradictory) {
+				const groupId = a.conflict_group_id ?? b.conflict_group_id ?? uuid();
+				if (a.conflict_group_id !== groupId) {
+					await db.execute("UPDATE graph_nodes SET conflict_group_id = ? WHERE id = ?", [
+						groupId,
+						a.id,
+					]);
+				}
+				if (b.conflict_group_id !== groupId) {
+					await db.execute("UPDATE graph_nodes SET conflict_group_id = ? WHERE id = ?", [
+						groupId,
+						b.id,
+					]);
+				}
+				conflicts++;
+			}
+		}
+	}
+
+	return conflicts;
+}

package/src/sync/dedup.ts

@@ -0,0 +1,183 @@
+// Module: dedup — three-layer deduplication for team sync
+
+import { wordJaccard } from "@/capture/consolidate";
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEdge } from "@/graph/edges";
+import type { Entity } from "@/graph/entities";
+import { invalidateEntity, updateEntity } from "@/graph/entities";
+import type { LlmClient } from "@/shared/llm-client";
+
+export interface DedupeResult {
+	merged: number;
+	flagged: number;
+	different: number;
+}
+
+function normalizeName(name: string): string {
+	return name
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9\-_]+/g, " ");
+}
+
+export function cosineSimilarity(a: Uint8Array | null, b: Uint8Array | null): number | null {
+	if (!a || !b) return null;
+	const fa = new Float32Array(a.buffer, a.byteOffset, Math.floor(a.byteLength / 4));
+	const fb = new Float32Array(b.buffer, b.byteOffset, Math.floor(b.byteLength / 4));
+	if (fa.length !== fb.length || fa.length === 0) return null;
+
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < fa.length; i++) {
+		dot += fa[i] * fb[i];
+		normA += fa[i] * fa[i];
+		normB += fb[i] * fb[i];
+	}
+	if (normA === 0 || normB === 0) return null;
+	return dot / Math.sqrt(normA * normB);
+}
+
+/**
+ * Compute the magnitude (L2 norm) of an embedding vector.
+ */
+function _embeddingMagnitude(e: Uint8Array | null): number | null {
+	if (!e) return null;
+	const f = new Float32Array(e.buffer, e.byteOffset, Math.floor(e.byteLength / 4));
+	if (f.length === 0) return null;
+	let sum = 0;
+	for (let i = 0; i < f.length; i++) {
+		sum += f[i] * f[i];
+	}
+	return Math.sqrt(sum);
+}
+
+/**
+ * Union two JSON-encoded string arrays.
+ */
+function unionJsonArrays(jsonA: string, jsonB: string): string {
+	let arrA: string[] = [];
+	let arrB: string[] = [];
+	try {
+		arrA = JSON.parse(jsonA);
+	} catch {
+		/* empty */
+	}
+	try {
+		arrB = JSON.parse(jsonB);
+	} catch {
+		/* empty */
+	}
+	const merged = [...new Set([...arrA, ...arrB])];
+	return JSON.stringify(merged);
+}
+
+/**
+ * Compute importance for a merged entity using time-decay weighted average.
+ */
+function mergedImportance(a: Entity, b: Entity, now: number): number {
+	const ageDaysA = (now - a.created_at) / 86400000;
+	const ageDaysB = (now - b.created_at) / 86400000;
+	const wA = Math.exp(-0.01 * ageDaysA);
+	const wB = Math.exp(-0.01 * ageDaysB);
+	return (a.importance * wA + b.importance * wB) / (wA + wB);
+}
+
+export async function deduplicateEntities(
+	db: SiaDb,
+	peerEntities: Entity[],
+	llmClient?: LlmClient,
+): Promise<DedupeResult> {
+	const localRows = await db.execute(
+		"SELECT * FROM graph_nodes WHERE archived_at IS NULL AND t_valid_until IS NULL",
+	);
+	const locals = localRows.rows as unknown as Entity[];
+	const now = Date.now();
+
+	const result: DedupeResult = { merged: 0, flagged: 0, different: 0 };
+
+	for (const peer of peerEntities) {
+		const peerNorm = normalizeName(peer.name);
+		const peerId = peer.created_by ?? "peer";
+		for (const local of locals) {
+			if (local.type !== peer.type) continue;
+
+			const nameJaccard = wordJaccard(peerNorm, normalizeName(local.name));
+			let decision: "merged" | "pending" | "different";
+
+			if (nameJaccard > 0.95) {
+				decision = "merged";
+			} else {
+				const cosine = cosineSimilarity(local.embedding, peer.embedding);
+				if (cosine !== null && cosine > 0.92) {
+					decision = "merged";
+				} else if (cosine !== null && cosine >= 0.8) {
+					decision = "pending";
+				} else {
+					decision = "different";
+				}
+			}
+
+			// Layer 3: LLM classification for pending pairs (0.80-0.92 range)
+			if (decision === "pending" && llmClient) {
+				const prompt = `Entity A: "${local.name}" — ${local.content}\nEntity B: "${peer.name}" — ${peer.content}\n\nAre these the same entity, different entities, or related entities?`;
+				const classification = await llmClient.classify(prompt, ["SAME", "DIFFERENT", "RELATED"]);
+
+				if (classification === "SAME") {
+					decision = "merged";
+				} else if (classification === "RELATED") {
+					// Create a relates_to edge
+					await insertEdge(db, {
+						from_id: local.id,
+						to_id: peer.id,
+						type: "relates_to",
+						weight: 0.6,
+					});
+					decision = "different";
+				} else {
+					decision = "different";
+				}
+			}
+
+			// Merge implementation for SAME decisions
+			if (decision === "merged") {
+				const mergedTags = unionJsonArrays(local.tags, peer.tags);
+				const mergedFilePaths = unionJsonArrays(local.file_paths, peer.file_paths);
+				const newTrustTier = Math.max(local.trust_tier, peer.trust_tier);
+				const newImportance = mergedImportance(local, peer, now);
+
+				let mergedContent = local.content;
+				if (llmClient) {
+					mergedContent = await llmClient.summarize(
+						`Synthesize a merged description from these two entity descriptions:\n1. ${local.content}\n2. ${peer.content}`,
+					);
+				}
+
+				await updateEntity(db, local.id, {
+					tags: mergedTags,
+					file_paths: mergedFilePaths,
+					trust_tier: newTrustTier,
+					importance: newImportance,
+					content: mergedContent,
+				});
+
+				// Invalidate the peer (losing entity)
+				await invalidateEntity(db, peer.id);
+
+				result.merged++;
+			} else if (decision === "pending") {
+				result.flagged++;
+			} else {
+				result.different++;
+			}
+
+			await db.execute(
+				`INSERT OR REPLACE INTO sync_dedup_log (entity_a_id, entity_b_id, peer_id, decision, checked_at)
+                                 VALUES (?, ?, ?, ?, ?)`,
+				[local.id, peer.id, peerId, decision, now],
+			);
+		}
+	}
+
+	return result;
+}