@rkarim08/sia 1.0.0

package/src/capture/edge-inferrer.ts

@@ -0,0 +1,161 @@
+// Module: edge-inferrer — Infer edges between new and existing entities
+
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEdge } from "@/graph/edges";
+import { getActiveEntities, getEntity } from "@/graph/entities";
+
+/** Maximum edges created per new entity. */
+const MAX_EDGES_PER_ENTITY = 5;
+
+/** Minimum weight threshold for creating an edge. */
+const MIN_WEIGHT = 0.3;
+
+/** Type affinity pairs: source type -> target type -> edge label. */
+const TYPE_AFFINITY: Record<string, { target: string; label: string }> = {
+	Solution: { target: "Bug", label: "solves" },
+	Bug: { target: "Solution", label: "solved_by" },
+};
+
+/**
+ * Compute tag overlap weight between two tag sets.
+ * Returns |intersection| / |union| (Jaccard similarity on tags).
+ */
+function tagOverlap(tagsA: string[], tagsB: string[]): number {
+	const setA = new Set(tagsA);
+	const setB = new Set(tagsB);
+
+	if (setA.size === 0 || setB.size === 0) return 0;
+
+	let intersectionSize = 0;
+	for (const tag of setA) {
+		if (setB.has(tag)) intersectionSize++;
+	}
+
+	const unionSize = setA.size + setB.size - intersectionSize;
+	if (unionSize === 0) return 0;
+
+	return intersectionSize / unionSize;
+}
+
+/**
+ * Safely parse a JSON tags string into a string array.
+ * Returns empty array on parse failure.
+ */
+function parseTags(raw: string): string[] {
+	try {
+		const parsed = JSON.parse(raw);
+		if (Array.isArray(parsed)) return parsed;
+		return [];
+	} catch {
+		return [];
+	}
+}
+
+interface EdgeCandidate {
+	targetId: string;
+	edgeType: string;
+	weight: number;
+}
+
+/**
+ * Infer edges between newly created entities and existing entities in the graph.
+ *
+ * For each new entity ID:
+ * 1. Get the entity via getEntity.
+ * 2. If entity has no tags and type is not 'Solution' or 'Bug', skip.
+ * 3. Query for related entities by same package_path, matching tags, or type affinity.
+ * 4. For type affinity: Solution entities look for Bug entities with overlapping tags -> 'solves' edge.
+ * 5. Create edges via insertEdge for matches with weight >= 0.3.
+ * 6. Cap at 5 edges per new entity.
+ *
+ * Returns total edges created.
+ */
+export async function inferEdges(db: SiaDb, newEntityIds: string[]): Promise<number> {
+	let totalCreated = 0;
+
+	for (const entityId of newEntityIds) {
+		const entity = await getEntity(db, entityId);
+		if (!entity) continue;
+
+		const tags = parseTags(entity.tags);
+		const hasTypeAffinity = entity.type in TYPE_AFFINITY;
+
+		// Skip entities with no tags and no type affinity
+		if (tags.length === 0 && !hasTypeAffinity) continue;
+
+		// Gather all active entities to find candidates
+		const allActive = await getActiveEntities(db);
+
+		const candidates: EdgeCandidate[] = [];
+
+		for (const other of allActive) {
+			// Skip self-edges
+			if (other.id === entityId) continue;
+
+			let bestWeight = 0;
+			let bestEdgeType = "relates_to";
+
+			// 1. Same package_path
+			if (entity.package_path && other.package_path && entity.package_path === other.package_path) {
+				const otherTags = parseTags(other.tags);
+				const overlap = tagOverlap(tags, otherTags);
+				// Package path match gives a base weight of 0.3, boosted by tag overlap
+				const w = 0.3 + overlap * 0.4;
+				if (w > bestWeight) {
+					bestWeight = w;
+					bestEdgeType = "relates_to";
+				}
+			}
+
+			// 2. Tag overlap (regardless of package path)
+			if (tags.length > 0) {
+				const otherTags = parseTags(other.tags);
+				const overlap = tagOverlap(tags, otherTags);
+				if (overlap > bestWeight) {
+					bestWeight = overlap;
+					bestEdgeType = "relates_to";
+				}
+			}
+
+			// 3. Type affinity (Solution<->Bug)
+			if (hasTypeAffinity) {
+				const affinity = TYPE_AFFINITY[entity.type];
+				if (other.type === affinity.target) {
+					const otherTags = parseTags(other.tags);
+					const overlap = tagOverlap(tags, otherTags);
+					// Type affinity gives a base boost of 0.35 + tag overlap contribution
+					const w = 0.35 + overlap * 0.55;
+					if (w > bestWeight) {
+						bestWeight = w;
+						bestEdgeType = affinity.label;
+					}
+				}
+			}
+
+			if (bestWeight >= MIN_WEIGHT) {
+				candidates.push({
+					targetId: other.id,
+					edgeType: bestEdgeType,
+					weight: bestWeight,
+				});
+			}
+		}
+
+		// Sort by weight descending and cap at MAX_EDGES_PER_ENTITY
+		candidates.sort((a, b) => b.weight - a.weight);
+		const toCreate = candidates.slice(0, MAX_EDGES_PER_ENTITY);
+
+		for (const candidate of toCreate) {
+			await insertEdge(db, {
+				from_id: entityId,
+				to_id: candidate.targetId,
+				type: candidate.edgeType,
+				weight: candidate.weight,
+				extraction_method: "edge-inferrer",
+			});
+			totalCreated++;
+		}
+	}
+
+	return totalCreated;
+}

package/src/capture/embedder.ts

@@ -0,0 +1,166 @@
+// Module: embedder — ONNX-based text embedding with lazy session initialization
+
+import { existsSync } from "node:fs";
+import type { Tokenizer } from "@/capture/tokenizer";
+import { loadTokenizer, tokenize } from "@/capture/tokenizer";
+
+/** Embedding vector dimension for all-MiniLM-L6-v2. */
+const EMBEDDING_DIM = 384;
+
+/** Maximum sequence length for tokenization. */
+const MAX_SEQ_LENGTH = 128;
+
+/**
+ * The Embedder interface: embed text into a float vector, and clean up resources.
+ */
+export interface Embedder {
+	embed(text: string, trustTier?: number): Promise<Float32Array | null>;
+	close(): void;
+}
+
+/**
+ * Try to load the onnxruntime-node module.
+ * Returns null if the module is unavailable (e.g., unsupported platform).
+ */
+async function loadOnnxRuntime(): Promise<typeof import("onnxruntime-node") | null> {
+	try {
+		return await import("onnxruntime-node");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Create an Embedder backed by an ONNX InferenceSession.
+ *
+ * The session is lazily initialized on the first call to embed().
+ * If the model file does not exist or ONNX runtime is unavailable, embed() returns null.
+ */
+export function createEmbedder(modelPath: string, tokenizerPath: string): Embedder {
+	let session: { run(feeds: Record<string, unknown>): Promise<Record<string, unknown>> } | null =
+		null;
+	let tokenizer: Tokenizer | null = null;
+	let initialized = false;
+	let ort: typeof import("onnxruntime-node") | null = null;
+
+	async function ensureSession(): Promise<boolean> {
+		if (initialized) return session !== null;
+		initialized = true;
+
+		if (!existsSync(modelPath)) {
+			return false;
+		}
+
+		if (!existsSync(tokenizerPath)) {
+			return false;
+		}
+
+		try {
+			tokenizer = loadTokenizer(tokenizerPath);
+		} catch {
+			return false;
+		}
+
+		try {
+			ort = await loadOnnxRuntime();
+			if (!ort) return false;
+
+			session = (await ort.InferenceSession.create(modelPath, {
+				executionProviders: ["cpu"],
+			})) as unknown as typeof session;
+			return true;
+		} catch {
+			session = null;
+			return false;
+		}
+	}
+
+	return {
+		async embed(text: string): Promise<Float32Array | null> {
+			const ready = await ensureSession();
+			if (!ready || !session || !tokenizer || !ort) return null;
+
+			const { inputIds, attentionMask } = tokenize(tokenizer, text, MAX_SEQ_LENGTH);
+
+			// Build token_type_ids (all zeros for single-sentence tasks)
+			const tokenTypeIds = new BigInt64Array(MAX_SEQ_LENGTH);
+
+			// Create ONNX tensors — shape [1, MAX_SEQ_LENGTH]
+			const shape = [1, MAX_SEQ_LENGTH] as const;
+			const feeds = {
+				input_ids: new ort.Tensor("int64", inputIds, shape),
+				attention_mask: new ort.Tensor("int64", attentionMask, shape),
+				token_type_ids: new ort.Tensor("int64", tokenTypeIds, shape),
+			};
+
+			const results = await session.run(feeds);
+
+			// last_hidden_state has shape [1, seq_len, 384]
+			const lastHiddenState = results.last_hidden_state as {
+				data: Float32Array;
+				dims: readonly number[];
+			};
+			if (!lastHiddenState?.data) return null;
+
+			const hiddenData = lastHiddenState.data;
+			const seqLen = lastHiddenState.dims[1] ?? MAX_SEQ_LENGTH;
+
+			// Mean pooling: average only non-padding token vectors
+			return meanPoolAndNormalize(hiddenData, attentionMask, seqLen, EMBEDDING_DIM);
+		},
+
+		close(): void {
+			if (session && "release" in session) {
+				(session as { release(): void }).release();
+			}
+			session = null;
+			tokenizer = null;
+			ort = null;
+			initialized = false;
+		},
+	};
+}
+
+/**
+ * Mean-pool the hidden states for non-padding tokens, then L2-normalize.
+ */
+function meanPoolAndNormalize(
+	hiddenData: Float32Array,
+	attentionMask: BigInt64Array,
+	seqLen: number,
+	dim: number,
+): Float32Array {
+	const pooled = new Float32Array(dim);
+	let tokenCount = 0;
+
+	for (let t = 0; t < seqLen; t++) {
+		if (attentionMask[t] === 0n) continue;
+		tokenCount++;
+		const offset = t * dim;
+		for (let d = 0; d < dim; d++) {
+			pooled[d] += hiddenData[offset + d];
+		}
+	}
+
+	// Average
+	if (tokenCount > 0) {
+		for (let d = 0; d < dim; d++) {
+			pooled[d] /= tokenCount;
+		}
+	}
+
+	// L2 normalize
+	let norm = 0;
+	for (let d = 0; d < dim; d++) {
+		norm += pooled[d] * pooled[d];
+	}
+	norm = Math.sqrt(norm);
+
+	if (norm > 0) {
+		for (let d = 0; d < dim; d++) {
+			pooled[d] /= norm;
+		}
+	}
+
+	return pooled;
+}

package/src/capture/embedding-cache.ts

@@ -0,0 +1,73 @@
+// Module: embedding-cache — LRU-cached wrapper around an Embedder with noEmbed and paranoid modes
+
+import { createHash } from "node:crypto";
+import type { Embedder } from "@/capture/embedder";
+
+/** Configuration options for the cached embedder. */
+export interface CacheOpts {
+	/** Maximum number of cache entries before LRU eviction kicks in. Default: 1000. */
+	maxSize?: number;
+	/** When true, embed() returns null immediately without loading the model. */
+	noEmbed?: boolean;
+	/** When true, embed() returns null for trustTier === 4 content. */
+	paranoid?: boolean;
+}
+
+/** Compute a SHA-256 hex digest of the given text. */
+function contentHash(text: string): string {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * Wrap an inner Embedder with LRU caching, noEmbed, and paranoid-mode support.
+ *
+ * - **LRU cache**: content-hash keyed (SHA-256 of text). Same text yields a
+ *   cache hit with no ONNX call. When full the oldest entry is evicted.
+ * - **noEmbed**: when `opts.noEmbed` is true, `embed()` returns null immediately.
+ * - **paranoid**: when `opts.paranoid` is true AND `trustTier === 4`, `embed()`
+ *   returns null immediately (Tier 4 content is never embedded).
+ */
+export function createCachedEmbedder(inner: Embedder, opts?: CacheOpts): Embedder {
+	const maxSize = opts?.maxSize ?? 1000;
+	const noEmbed = opts?.noEmbed ?? false;
+	const paranoid = opts?.paranoid ?? false;
+
+	// Map preserves insertion order, which we exploit for LRU eviction.
+	const cache = new Map<string, Float32Array | null>();
+
+	return {
+		async embed(text: string, trustTier?: number): Promise<Float32Array | null> {
+			// --no-embed: short-circuit without touching model
+			if (noEmbed) return null;
+
+			// paranoid mode: block Tier 4 content
+			if (paranoid && trustTier === 4) return null;
+
+			const key = contentHash(text);
+
+			// Cache hit — move entry to end (most-recently-used)
+			const cached = cache.get(key);
+			if (cached !== undefined) {
+				cache.delete(key);
+				cache.set(key, cached);
+				return cached;
+			}
+
+			// Cache miss — delegate to inner embedder
+			const result = await inner.embed(text, trustTier);
+
+			// Evict oldest entry if cache is full
+			if (cache.size >= maxSize) {
+				const oldest = cache.keys().next().value as string;
+				cache.delete(oldest);
+			}
+
+			cache.set(key, result);
+			return result;
+		},
+
+		close(): void {
+			inner.close();
+		},
+	};
+}

package/src/capture/flag-processor.ts

@@ -0,0 +1,64 @@
+// Module: flag-processor — Converts unconsumed session flags into graph entities
+
+import { consolidate } from "@/capture/consolidate";
+import type { CandidateFact } from "@/capture/types";
+import type { SiaDb } from "@/graph/db-interface";
+import { updateEntity } from "@/graph/entities";
+import { getUnconsumedFlags, markFlagConsumed } from "@/graph/flags";
+import type { SiaConfig } from "@/shared/config";
+
+const DEFAULT_BASE_IMPORTANCE = 0.5;
+
+/**
+ * Process all unconsumed session flags for the given session.
+ *
+ * For each flag:
+ * 1. Build a CandidateFact of type "Concept" from the flag reason.
+ * 2. Apply the configured flaggedConfidenceThreshold and flaggedImportanceBoost.
+ * 3. Run the candidate through the consolidation pipeline.
+ * 4. Mark the flag as consumed.
+ *
+ * Returns the number of flags processed (0 when flagging is disabled).
+ */
+export async function processFlags(
+	db: SiaDb,
+	sessionId: string,
+	config: SiaConfig,
+): Promise<number> {
+	if (!config.enableFlagging) return 0;
+
+	const flags = await getUnconsumedFlags(db, sessionId);
+
+	for (const flag of flags) {
+		const candidate: CandidateFact = {
+			type: "Concept",
+			name: flag.reason.slice(0, 50),
+			content: flag.reason,
+			summary: flag.reason.slice(0, 80),
+			tags: ["session-flag"],
+			file_paths: [],
+			trust_tier: 1,
+			confidence: config.flaggedConfidenceThreshold,
+		};
+
+		await consolidate(db, [candidate]);
+
+		// Apply the importance boost to the entity just created/updated
+		const boostedImportance = DEFAULT_BASE_IMPORTANCE + config.flaggedImportanceBoost;
+		const result = await db.execute(
+			"SELECT id FROM graph_nodes WHERE name = ? AND type = 'Concept' AND t_valid_until IS NULL AND archived_at IS NULL",
+			[candidate.name],
+		);
+		const row = result.rows[0] as { id: string } | undefined;
+		if (row) {
+			await updateEntity(db, row.id, {
+				base_importance: boostedImportance,
+				importance: boostedImportance,
+			});
+		}
+
+		await markFlagConsumed(db, flag.id);
+	}
+
+	return flags.length;
+}

package/src/capture/hook.ts

@@ -0,0 +1,67 @@
+// Module: hook — Hook entry point for capturing Claude Code events
+
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import type { HookPayload } from "@/capture/types";
+import { resolveWorktreeRoot } from "@/shared/git-utils";
+
+export type { HookPayload };
+
+/**
+ * Parse raw stdin JSON into a validated HookPayload.
+ * Throws on invalid JSON or missing required fields.
+ */
+export function parseHookPayload(stdin: string): HookPayload {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdin);
+	} catch {
+		throw new Error("Invalid JSON in hook payload");
+	}
+
+	if (typeof parsed !== "object" || parsed === null) {
+		throw new Error("Hook payload must be a JSON object");
+	}
+
+	const obj = parsed as Record<string, unknown>;
+
+	if (typeof obj.cwd !== "string" || obj.cwd.length === 0) {
+		throw new Error("Hook payload missing required field: cwd");
+	}
+	if (obj.type !== "PostToolUse" && obj.type !== "Stop") {
+		throw new Error("Hook payload field 'type' must be 'PostToolUse' or 'Stop'");
+	}
+	if (typeof obj.sessionId !== "string" || obj.sessionId.length === 0) {
+		throw new Error("Hook payload missing required field: sessionId");
+	}
+	if (typeof obj.content !== "string") {
+		throw new Error("Hook payload missing required field: content");
+	}
+
+	return {
+		cwd: obj.cwd as string,
+		type: obj.type as "PostToolUse" | "Stop",
+		sessionId: obj.sessionId as string,
+		content: obj.content as string,
+		toolName: typeof obj.toolName === "string" ? obj.toolName : undefined,
+		filePath: typeof obj.filePath === "string" ? obj.filePath : undefined,
+	};
+}
+
+/**
+ * Derive a stable repo identifier from a working directory path.
+ * Uses the git worktree root so that all paths within the same repo
+ * (including subdirectories) resolve to the same hash.
+ * Falls back to realpathSync for non-git directories (with a warning).
+ */
+export function resolveRepoHash(cwd: string): string {
+	const root = resolveWorktreeRoot(cwd);
+	if (!root) {
+		console.error(
+			`[sia] WARNING: Cannot determine git root for "${cwd}". ` +
+				"Using directory path as repo hash — graph data may diverge if git becomes available later.",
+		);
+		return createHash("sha256").update(realpathSync(cwd)).digest("hex");
+	}
+	return createHash("sha256").update(root).digest("hex");
+}