@rkarim08/sia 1.0.0

package/src/native/bridge.ts

@@ -0,0 +1,167 @@
+// Module: native/bridge — Single import site for the native performance module
+// Three-tier fallback: native → wasm → typescript
+//
+// Since @sia/native and @sia/native-wasm do not exist yet, this always
+// falls back to the pure TypeScript implementations.
+
+import { fallbackAstDiff } from "./fallback-ast-diff";
+import { fallbackGraphCompute } from "./fallback-graph";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface AstDiffResult {
+	inserts: Array<{ node_id: string; kind: string; name: string }>;
+	removes: Array<{ node_id: string }>;
+	updates: Array<{ node_id: string; old_name: string; new_name: string }>;
+	moves: Array<{ node_id: string; old_parent: string; new_parent: string }>;
+}
+
+export interface GraphComputeResult {
+	scores: Float64Array;
+	node_ids: string[];
+}
+
+export type GraphAlgorithm =
+	| { kind: "pagerank"; damping: number; iterations: number; seed_nodes?: string[] }
+	| { kind: "shortest_path"; source: string }
+	| { kind: "betweenness_centrality" }
+	| { kind: "connected_components" };
+
+// ---------------------------------------------------------------------------
+// Tier detection
+// ---------------------------------------------------------------------------
+
+export type NativeModuleStatus = "native" | "wasm" | "typescript";
+
+let _cachedStatus: NativeModuleStatus | null = null;
+
+/**
+ * Probe the three tiers in order and return which one is available:
+ * 1. `@sia/native`      — compiled Rust module
+ * 2. `@sia/native-wasm` — WASM build of the same Rust module
+ * 3. `typescript`       — pure TS fallback (always available)
+ */
+export function isNativeAvailable(): NativeModuleStatus {
+	return getNativeModuleStatus();
+}
+
+/**
+ * Detect which implementation is active:
+ * - "native"     — native Rust module loaded successfully
+ * - "wasm"       — WASM fallback loaded successfully
+ * - "typescript" — pure TypeScript fallback (no compiled module)
+ */
+export function getNativeModuleStatus(): NativeModuleStatus {
+	if (_cachedStatus !== null) {
+		return _cachedStatus;
+	}
+
+	// Attempt to load the native Rust module
+	try {
+		require("@sia/native");
+		_cachedStatus = "native";
+		return _cachedStatus;
+	} catch {
+		// not installed
+	}
+
+	// Attempt to load the WASM build
+	try {
+		require("@sia/native-wasm");
+		_cachedStatus = "wasm";
+		return _cachedStatus;
+	} catch {
+		// not installed
+	}
+
+	// Pure TypeScript fallback
+	_cachedStatus = "typescript";
+	return _cachedStatus;
+}
+
+/**
+ * Reset the cached status (for testing).
+ */
+export function _resetNativeStatusCache(): void {
+	_cachedStatus = null;
+}
+
+// ---------------------------------------------------------------------------
+// Lazy native module handle
+// ---------------------------------------------------------------------------
+
+interface NativeModule {
+	astDiff(
+		oldTreeBytes: Uint8Array,
+		newTreeBytes: Uint8Array,
+		nodeIdMap: Map<number, string>,
+	): AstDiffResult;
+	graphCompute(edges: Int32Array, nodeIds: string[], algorithm: GraphAlgorithm): GraphComputeResult;
+}
+
+function loadNativeModule(pkg: string): NativeModule | null {
+	try {
+		return require(pkg) as NativeModule;
+	} catch {
+		return null;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Public API — routes to the best available implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Diff two AST trees encoded as byte arrays.
+ *
+ * In the TypeScript fallback the bytes are JSON-encoded arrays of
+ * `{name, kind, parent}` objects. `nodeIdMap` maps positional indices in the
+ * old tree to stable node IDs.
+ */
+export function astDiff(
+	oldTreeBytes: Uint8Array,
+	newTreeBytes: Uint8Array,
+	nodeIdMap: Map<number, string>,
+): AstDiffResult {
+	const tier = getNativeModuleStatus();
+
+	if (tier === "native") {
+		const mod = loadNativeModule("@sia/native");
+		if (mod) return mod.astDiff(oldTreeBytes, newTreeBytes, nodeIdMap);
+	}
+
+	if (tier === "wasm") {
+		const mod = loadNativeModule("@sia/native-wasm");
+		if (mod) return mod.astDiff(oldTreeBytes, newTreeBytes, nodeIdMap);
+	}
+
+	return fallbackAstDiff(oldTreeBytes, newTreeBytes, nodeIdMap);
+}
+
+/**
+ * Run a graph algorithm on a flat edge list.
+ *
+ * `edges` is a flat Int32Array of `[from, to, from, to, …]` pairs where
+ * indices refer to positions in `nodeIds`.
+ */
+export function graphCompute(
+	edges: Int32Array,
+	nodeIds: string[],
+	algorithm: GraphAlgorithm,
+): GraphComputeResult {
+	const tier = getNativeModuleStatus();
+
+	if (tier === "native") {
+		const mod = loadNativeModule("@sia/native");
+		if (mod) return mod.graphCompute(edges, nodeIds, algorithm);
+	}
+
+	if (tier === "wasm") {
+		const mod = loadNativeModule("@sia/native-wasm");
+		if (mod) return mod.graphCompute(edges, nodeIds, algorithm);
+	}
+
+	return fallbackGraphCompute(edges, nodeIds, algorithm);
+}

package/src/native/fallback-ast-diff.ts

@@ -0,0 +1,144 @@
+// Module: fallback-ast-diff — TypeScript fallback for AST diff
+// Correctness over performance. For the native/wasm implementation see @sia/native.
+
+import type { AstDiffResult } from "./bridge";
+
+interface AstNode {
+	name: string;
+	kind: string;
+	parent: string | null;
+}
+
+function parseTree(bytes: Uint8Array): AstNode[] {
+	try {
+		const text = new TextDecoder().decode(bytes);
+		const parsed = JSON.parse(text) as unknown;
+		if (!Array.isArray(parsed)) return [];
+		return (parsed as unknown[]).map((item) => {
+			const obj = item as Record<string, unknown>;
+			return {
+				name: String(obj.name ?? ""),
+				kind: String(obj.kind ?? ""),
+				parent: obj.parent != null ? String(obj.parent) : null,
+			};
+		});
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Name-based AST diff: compares two sets of extracted symbols to detect
+ * inserts, removes, updates, and moves.
+ *
+ * The old/new trees are encoded as JSON arrays of {name, kind, parent} objects.
+ * nodeIdMap maps positional indices to stable node IDs (used for removes).
+ */
+export function fallbackAstDiff(
+	oldTreeBytes: Uint8Array,
+	newTreeBytes: Uint8Array,
+	nodeIdMap: Map<number, string>,
+): AstDiffResult {
+	const oldNodes = parseTree(oldTreeBytes);
+	const newNodes = parseTree(newTreeBytes);
+
+	// Index old nodes by name for O(1) lookup
+	const oldByName = new Map<string, { node: AstNode; index: number }[]>();
+	for (let i = 0; i < oldNodes.length; i++) {
+		const node = oldNodes[i];
+		if (!oldByName.has(node.name)) {
+			oldByName.set(node.name, []);
+		}
+		oldByName.get(node.name)?.push({ node, index: i });
+	}
+
+	// Index new nodes by name
+	const newByName = new Map<string, { node: AstNode; index: number }[]>();
+	for (let j = 0; j < newNodes.length; j++) {
+		const node = newNodes[j];
+		if (!newByName.has(node.name)) {
+			newByName.set(node.name, []);
+		}
+		newByName.get(node.name)?.push({ node, index: j });
+	}
+
+	const inserts: AstDiffResult["inserts"] = [];
+	const removes: AstDiffResult["removes"] = [];
+	const updates: AstDiffResult["updates"] = [];
+	const moves: AstDiffResult["moves"] = [];
+
+	// Track which old/new nodes have been matched
+	const matchedOld = new Set<number>();
+	const matchedNew = new Set<number>();
+
+	// Exact matches first: same name, kind, and parent
+	for (const [name, oldEntries] of oldByName) {
+		const newEntries = newByName.get(name);
+		if (!newEntries) continue;
+
+		for (const oldEntry of oldEntries) {
+			for (const newEntry of newEntries) {
+				if (matchedOld.has(oldEntry.index) || matchedNew.has(newEntry.index)) continue;
+				if (oldEntry.node.kind === newEntry.node.kind) {
+					matchedOld.add(oldEntry.index);
+					matchedNew.add(newEntry.index);
+					// Check for moves (same name+kind but different parent)
+					if (oldEntry.node.parent !== newEntry.node.parent) {
+						const nodeId = nodeIdMap.get(oldEntry.index) ?? `node-${oldEntry.index}`;
+						moves.push({
+							node_id: nodeId,
+							old_parent: oldEntry.node.parent ?? "",
+							new_parent: newEntry.node.parent ?? "",
+						});
+					}
+					break;
+				}
+			}
+		}
+	}
+
+	// Partial matches: same name, different kind (update)
+	for (const [name, oldEntries] of oldByName) {
+		const newEntries = newByName.get(name);
+		if (!newEntries) continue;
+
+		for (const oldEntry of oldEntries) {
+			if (matchedOld.has(oldEntry.index)) continue;
+			for (const newEntry of newEntries) {
+				if (matchedNew.has(newEntry.index)) continue;
+				// Different kind — treat as an update
+				const nodeId = nodeIdMap.get(oldEntry.index) ?? `node-${oldEntry.index}`;
+				updates.push({
+					node_id: nodeId,
+					old_name: oldEntry.node.name,
+					new_name: newEntry.node.name,
+				});
+				matchedOld.add(oldEntry.index);
+				matchedNew.add(newEntry.index);
+				break;
+			}
+		}
+	}
+
+	// Removes: unmatched old nodes
+	for (let i = 0; i < oldNodes.length; i++) {
+		if (!matchedOld.has(i)) {
+			const nodeId = nodeIdMap.get(i) ?? `node-${i}`;
+			removes.push({ node_id: nodeId });
+		}
+	}
+
+	// Inserts: unmatched new nodes
+	for (let j = 0; j < newNodes.length; j++) {
+		if (!matchedNew.has(j)) {
+			const node = newNodes[j];
+			inserts.push({
+				node_id: `new-${j}`,
+				kind: node.kind,
+				name: node.name,
+			});
+		}
+	}
+
+	return { inserts, removes, updates, moves };
+}

package/src/native/fallback-graph.ts

@@ -0,0 +1,325 @@
+// Module: fallback-graph — Pure TypeScript graph algorithm implementations
+// Used when the native Rust module is unavailable.
+
+import type { GraphAlgorithm, GraphComputeResult } from "./bridge";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Build adjacency list from flat Int32Array of [from, to] pairs. */
+function buildAdjacency(edges: Int32Array, nodeCount: number): Map<number, number[]> {
+	const adj = new Map<number, number[]>();
+	for (let i = 0; i < nodeCount; i++) adj.set(i, []);
+
+	for (let i = 0; i < edges.length - 1; i += 2) {
+		const from = edges[i];
+		const to = edges[i + 1];
+		if (from >= 0 && to >= 0) {
+			adj.get(from)?.push(to);
+		}
+	}
+	return adj;
+}
+
+// ---------------------------------------------------------------------------
+// PageRank (power iteration)
+// ---------------------------------------------------------------------------
+
+function pagerank(
+	edges: Int32Array,
+	nodeIds: string[],
+	damping: number,
+	maxIterations: number,
+	_seedNodes?: string[],
+): Float64Array {
+	const n = nodeIds.length;
+	if (n === 0) return new Float64Array(0);
+
+	// outDegree[i] = number of out-edges from node i
+	const outDegree = new Int32Array(n);
+	for (let i = 0; i < edges.length - 1; i += 2) {
+		const from = edges[i];
+		if (from >= 0 && from < n) {
+			outDegree[from]++;
+		}
+	}
+
+	// Incoming edge map: to -> [from, ...]
+	const incoming = new Map<number, number[]>();
+	for (let i = 0; i < n; i++) incoming.set(i, []);
+	for (let i = 0; i < edges.length - 1; i += 2) {
+		const from = edges[i];
+		const to = edges[i + 1];
+		if (from >= 0 && to >= 0 && from < n && to < n) {
+			incoming.get(to)?.push(from);
+		}
+	}
+
+	let scores = new Float64Array(n).fill(1 / n);
+	const uniform = 1 / n;
+
+	for (let iter = 0; iter < maxIterations; iter++) {
+		const next = new Float64Array(n);
+
+		// Dangling node mass (nodes with no out-edges)
+		let dangling = 0;
+		for (let i = 0; i < n; i++) {
+			if (outDegree[i] === 0) dangling += scores[i];
+		}
+
+		for (let v = 0; v < n; v++) {
+			let rank = dangling * uniform; // spread dangling mass uniformly
+			for (const u of incoming.get(v) ?? []) {
+				rank += scores[u] / outDegree[u];
+			}
+			next[v] = (1 - damping) * uniform + damping * rank;
+		}
+
+		let delta = 0;
+		for (let i = 0; i < n; i++) {
+			delta += Math.abs(next[i] - scores[i]);
+		}
+		scores = next;
+		if (delta < 1e-8) break;
+	}
+
+	return scores;
+}
+
+// ---------------------------------------------------------------------------
+// Dijkstra (shortest path from source)
+// ---------------------------------------------------------------------------
+
+function dijkstra(edges: Int32Array, nodeIds: string[], source: string): Float64Array {
+	const n = nodeIds.length;
+	if (n === 0) return new Float64Array(0);
+
+	const sourceIdx = nodeIds.indexOf(source);
+	const dist = new Float64Array(n).fill(Number.POSITIVE_INFINITY);
+	if (sourceIdx < 0) return dist;
+
+	dist[sourceIdx] = 0;
+
+	// Min-heap: [dist, nodeIndex]
+	// Simple binary min-heap implementation
+	const heap: Array<[number, number]> = [[0, sourceIdx]];
+
+	function heapPush(item: [number, number]): void {
+		heap.push(item);
+		let i = heap.length - 1;
+		while (i > 0) {
+			const parent = Math.floor((i - 1) / 2);
+			if (heap[parent][0] <= heap[i][0]) break;
+			[heap[parent], heap[i]] = [heap[i], heap[parent]];
+			i = parent;
+		}
+	}
+
+	function heapPop(): [number, number] | undefined {
+		if (heap.length === 0) return undefined;
+		const top = heap[0];
+		const last = heap.pop();
+		if (last !== undefined && heap.length > 0) {
+			heap[0] = last;
+			let i = 0;
+			while (true) {
+				const left = 2 * i + 1;
+				const right = 2 * i + 2;
+				let smallest = i;
+				if (left < heap.length && heap[left][0] < heap[smallest][0]) smallest = left;
+				if (right < heap.length && heap[right][0] < heap[smallest][0]) smallest = right;
+				if (smallest === i) break;
+				[heap[i], heap[smallest]] = [heap[smallest], heap[i]];
+				i = smallest;
+			}
+		}
+		return top;
+	}
+
+	// Build adjacency with unit weights (edge length = 1)
+	const adj = buildAdjacency(edges, n);
+
+	while (heap.length > 0) {
+		const top = heapPop();
+		if (!top) break;
+		const [d, u] = top;
+		if (d > dist[u]) continue; // stale entry
+		for (const v of adj.get(u) ?? []) {
+			const nd = dist[u] + 1;
+			if (nd < dist[v]) {
+				dist[v] = nd;
+				heapPush([nd, v]);
+			}
+		}
+	}
+
+	return dist;
+}
+
+// ---------------------------------------------------------------------------
+// Union-Find (connected components)
+// ---------------------------------------------------------------------------
+
+function connectedComponents(edges: Int32Array, nodeCount: number): Float64Array {
+	if (nodeCount === 0) return new Float64Array(0);
+
+	const parent = new Int32Array(nodeCount);
+	const rank = new Int32Array(nodeCount);
+	for (let i = 0; i < nodeCount; i++) parent[i] = i;
+
+	function find(x: number): number {
+		let cur = x;
+		while (parent[cur] !== cur) {
+			parent[cur] = parent[parent[cur]]; // path halving
+			cur = parent[cur];
+		}
+		return cur;
+	}
+
+	function union(a: number, b: number): void {
+		const ra = find(a);
+		const rb = find(b);
+		if (ra === rb) return;
+		if (rank[ra] < rank[rb]) {
+			parent[ra] = rb;
+		} else if (rank[ra] > rank[rb]) {
+			parent[rb] = ra;
+		} else {
+			parent[rb] = ra;
+			rank[ra]++;
+		}
+	}
+
+	for (let i = 0; i < edges.length - 1; i += 2) {
+		const from = edges[i];
+		const to = edges[i + 1];
+		if (from >= 0 && to >= 0 && from < nodeCount && to < nodeCount) {
+			union(from, to);
+		}
+	}
+
+	// Assign compact component labels
+	const rootToLabel = new Map<number, number>();
+	let nextLabel = 0;
+	const result = new Float64Array(nodeCount);
+	for (let i = 0; i < nodeCount; i++) {
+		const root = find(i);
+		if (!rootToLabel.has(root)) {
+			rootToLabel.set(root, nextLabel++);
+		}
+		result[i] = rootToLabel.get(root) ?? 0;
+	}
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Brandes betweenness centrality
+// ---------------------------------------------------------------------------
+
+function betweennessCentrality(edges: Int32Array, nodeIds: string[]): Float64Array {
+	const n = nodeIds.length;
+	if (n === 0) return new Float64Array(0);
+
+	const adj = new Map<number, number[]>();
+	for (let i = 0; i < n; i++) adj.set(i, []);
+	for (let i = 0; i < edges.length - 1; i += 2) {
+		const from = edges[i];
+		const to = edges[i + 1];
+		if (from >= 0 && to >= 0 && from < n && to < n) {
+			adj.get(from)?.push(to);
+			adj.get(to)?.push(from); // treat as undirected for betweenness
+		}
+	}
+
+	// Deduplicate adjacency
+	for (const [k, v] of adj) {
+		adj.set(k, [...new Set(v)]);
+	}
+
+	const betweenness = new Float64Array(n);
+
+	for (let s = 0; s < n; s++) {
+		const stack: number[] = [];
+		const pred: number[][] = Array.from({ length: n }, () => []);
+		const sigma = new Float64Array(n); // number of shortest paths from s
+		const dist = new Float64Array(n).fill(-1);
+
+		sigma[s] = 1;
+		dist[s] = 0;
+		const queue: number[] = [s];
+
+		while (queue.length > 0) {
+			const v = queue.shift();
+			if (v === undefined) break;
+			stack.push(v);
+			for (const w of adj.get(v) ?? []) {
+				if (dist[w] < 0) {
+					queue.push(w);
+					dist[w] = dist[v] + 1;
+				}
+				if (dist[w] === dist[v] + 1) {
+					sigma[w] += sigma[v];
+					pred[w].push(v);
+				}
+			}
+		}
+
+		const delta = new Float64Array(n);
+		while (stack.length > 0) {
+			const w = stack.pop();
+			if (w === undefined) break;
+			for (const v of pred[w]) {
+				delta[v] += (sigma[v] / sigma[w]) * (1 + delta[w]);
+			}
+			if (w !== s) betweenness[w] += delta[w];
+		}
+	}
+
+	// Normalize (undirected: divide by 2)
+	for (let i = 0; i < n; i++) {
+		betweenness[i] /= 2;
+	}
+
+	return betweenness;
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function fallbackGraphCompute(
+	edges: Int32Array,
+	nodeIds: string[],
+	algorithm: GraphAlgorithm,
+): GraphComputeResult {
+	let scores: Float64Array;
+
+	switch (algorithm.kind) {
+		case "pagerank":
+			scores = pagerank(
+				edges,
+				nodeIds,
+				algorithm.damping,
+				algorithm.iterations,
+				algorithm.seed_nodes,
+			);
+			break;
+		case "shortest_path":
+			scores = dijkstra(edges, nodeIds, algorithm.source);
+			break;
+		case "connected_components":
+			scores = connectedComponents(edges, nodeIds.length);
+			break;
+		case "betweenness_centrality":
+			scores = betweennessCentrality(edges, nodeIds);
+			break;
+		default: {
+			// Exhaustive check
+			const _never: never = algorithm;
+			throw new Error(`Unknown algorithm: ${JSON.stringify(_never)}`);
+		}
+	}
+
+	return { scores, node_ids: nodeIds };
+}

package/src/ontology/constraints.ts

@@ -0,0 +1,56 @@
+// Module: constraints — Application-layer edge validation using edge_constraints table
+
+import type { SiaDb } from "@/graph/db-interface";
+
+/** Shape of a row in the edge_constraints table. */
+export interface EdgeConstraint {
+	id: number;
+	source_type: string;
+	edge_type: string;
+	target_type: string;
+	description: string | null;
+	cardinality: string;
+	required: number;
+}
+
+/**
+ * Check whether a (source_type, edge_type, target_type) triple exists
+ * in the edge_constraints table.
+ *
+ * Returns true if the triple is declared valid, false otherwise.
+ */
+export async function validateEdge(
+	db: SiaDb,
+	sourceType: string,
+	edgeType: string,
+	targetType: string,
+): Promise<boolean> {
+	const result = await db.execute(
+		`SELECT COUNT(*) AS cnt FROM edge_constraints
+		 WHERE source_type = ? AND edge_type = ? AND target_type = ?`,
+		[sourceType, edgeType, targetType],
+	);
+	const row = result.rows[0] as { cnt: number } | undefined;
+	return (row?.cnt ?? 0) > 0;
+}
+
+/**
+ * Return all valid edge constraint rows for a given source entity type.
+ */
+export async function getConstraintsForType(
+	db: SiaDb,
+	sourceType: string,
+): Promise<EdgeConstraint[]> {
+	const result = await db.execute("SELECT * FROM edge_constraints WHERE source_type = ?", [
+		sourceType,
+	]);
+	return result.rows as unknown as EdgeConstraint[];
+}
+
+/**
+ * Return the entire constraint set from the edge_constraints table.
+ */
+export async function getAllConstraints(db: SiaDb): Promise<EdgeConstraint[]> {
+	const result = await db.execute("SELECT * FROM edge_constraints", []);
+	return result.rows as unknown as EdgeConstraint[];
+}

package/src/ontology/errors.ts

@@ -0,0 +1,8 @@
+// Module: errors — Ontology-specific error types
+
+export class OntologyError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "OntologyError";
+	}
+}