understanding-graph 0.1.0

package/packages/core/dist/services/GraphStore.js

@@ -0,0 +1,2244 @@
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import GraphConstructor from 'graphology';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import louvainFn from 'graphology-communities-louvain';
+import { bidirectional } from 'graphology-shortest-path';
+import { bfsFromNode } from 'graphology-traversal';
+import { v4 as uuidv4 } from 'uuid';
+import { getDb, logEvent } from '../database/sqlite.js';
+import { bufferToEmbedding, cosineSimilarity, embeddingToBuffer, generateEmbedding, generateNodeEmbedding, } from './EmbeddingService.js';
+// ============================================================================
+// GraphStore Class
+// ============================================================================
+export class GraphStore {
+    graph = null;
+    nodesCache = new Map();
+    edgesCache = new Map();
+    dirty = true;
+    // --------------------------------------------------------------------------
+    // Internal helpers
+    // --------------------------------------------------------------------------
+    parseJson(value, defaultValue) {
+        if (!value)
+            return defaultValue;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    rowToNode(row) {
+        // Parse embedding from BLOB if present
+        let embedding = null;
+        if (row.embedding && Buffer.isBuffer(row.embedding)) {
+            embedding = bufferToEmbedding(row.embedding);
+        }
+        return {
+            id: row.id,
+            title: row.title,
+            trigger: row.trigger || null,
+            why: row.why || null,
+            understanding: row.understanding || null,
+            sourceElements: this.parseJson(row.source_elements, null),
+            validated: row.validated === null ? null : Boolean(row.validated),
+            active: Boolean(row.active),
+            version: row.version || 1,
+            revisions: this.parseJson(row.revisions, []),
+            conversationId: row.conversation_id || null,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at || null,
+            archivedAt: row.archived_at || null,
+            archiveReason: row.archive_reason || null,
+            embedding,
+            references: this.parseJson(row.references, null),
+            // Document fields
+            content: row.content || null,
+            summary: row.summary || null,
+            level: row.level || null,
+            isDocRoot: row.is_doc_root === null ? null : Boolean(row.is_doc_root),
+            fileType: row.file_type || null,
+            // Flexible metadata
+            metadata: this.parseJson(row.metadata, {}),
+        };
+    }
+    rowToEdge(row) {
+        const fromId = row.from_id;
+        const toId = row.to_id;
+        return {
+            id: row.id,
+            fromId,
+            toId,
+            from: fromId, // Alias for client compatibility
+            to: toId, // Alias for client compatibility
+            type: row.type || 'relates',
+            explanation: row.explanation || null,
+            why: row.why || null,
+            active: Boolean(row.active),
+            version: row.version || 1,
+            revisions: this.parseJson(row.revisions, []),
+            conversationId: row.conversation_id || null,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at || null,
+        };
+    }
+    markDirty() {
+        this.dirty = true;
+    }
+    // --------------------------------------------------------------------------
+    // Graph loading
+    // --------------------------------------------------------------------------
+    /**
+     * Load the full graph from SQLite into graphology.
+     * Call this at session start or after detecting dirty state.
+     */
+    loadGraph(options = {}) {
+        const { includeInactive = false } = options;
+        const db = getDb();
+        // biome-ignore lint/suspicious/noExplicitAny: graphology ESM/CJS compatibility
+        this.graph = new GraphConstructor({
+            type: 'directed',
+            allowSelfLoops: false,
+        });
+        this.nodesCache.clear();
+        this.edgesCache.clear();
+        // Load nodes
+        const nodeQuery = includeInactive
+            ? 'SELECT * FROM nodes'
+            : 'SELECT * FROM nodes WHERE active = 1';
+        const nodeRows = db.prepare(nodeQuery).all();
+        for (const row of nodeRows) {
+            const node = this.rowToNode(row);
+            this.nodesCache.set(node.id, node);
+            this.graph.addNode(node.id, { ...node });
+        }
+        // Load edges
+        const edgeQuery = includeInactive
+            ? 'SELECT * FROM edges'
+            : 'SELECT * FROM edges WHERE active = 1';
+        const edgeRows = db.prepare(edgeQuery).all();
+        for (const row of edgeRows) {
+            const edge = this.rowToEdge(row);
+            this.edgesCache.set(edge.id, edge);
+            // Only add edge if both endpoints exist and edge doesn't already exist
+            if (this.graph.hasNode(edge.fromId) &&
+                this.graph.hasNode(edge.toId) &&
+                !this.graph.hasEdge(edge.fromId, edge.toId)) {
+                this.graph.addEdge(edge.fromId, edge.toId, { ...edge, key: edge.id });
+            }
+        }
+        this.dirty = false;
+        return this.graph;
+    }
+    /**
+     * Get the graphology instance (loads if needed)
+     */
+    getGraph() {
+        if (!this.graph || this.dirty) {
+            this.loadGraph();
+        }
+        if (!this.graph) {
+            throw new Error('Failed to load graph');
+        }
+        return this.graph;
+    }
+    // --------------------------------------------------------------------------
+    // Node CRUD
+    // --------------------------------------------------------------------------
+    createNode(input) {
+        // --- STRICT VALIDATION (Impossible to create illegal nodes) ---
+        const isDocument = !!input.content || !!input.level;
+        if (isDocument) {
+            if (!input.title || !input.content) {
+                throw new Error("ILLEGAL_DOCUMENT_NODE: Document nodes MUST have 'title' and 'content'.");
+            }
+        }
+        else {
+            // Concept node validation
+            const missing = [];
+            if (!input.title)
+                missing.push('title');
+            if (!input.trigger)
+                missing.push('trigger');
+            if (!input.why)
+                missing.push('why');
+            if (!input.understanding)
+                missing.push('understanding');
+            if (missing.length > 0) {
+                throw new Error(`ILLEGAL_CONCEPT_NODE: Missing required fields: ${missing.join(', ')}. Every concept must capture its metabolic intent (trigger, why, understanding).`);
+            }
+        }
+        const db = getDb();
+        const id = `n_${uuidv4().slice(0, 8)}`;
+        const isSerendipity = input.trigger === 'serendipity';
+        const stmt = db.prepare(`
+      INSERT INTO nodes (id, title, trigger, why, understanding, source_elements, validated, conversation_id, tool_call_id, content, summary, level, is_doc_root, file_type, "references", metadata)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(id, input.title, input.trigger || null, input.why || null, input.understanding || null, input.sourceElements ? JSON.stringify(input.sourceElements) : null, isSerendipity ? 0 : null, input.conversationId, input.toolCallId ?? null, input.content || null, input.summary || null, input.level || null, input.isDocRoot ? 1 : null, input.fileType || null, input.references ? JSON.stringify(input.references) : null, input.metadata ? JSON.stringify(input.metadata) : '{}');
+        // Log event
+        const seq = logEvent('created', 'node', id, input.conversationId, `Created concept: ${input.title}`);
+        this.markDirty();
+        // Return the created node
+        const row = db
+            .prepare('SELECT * FROM nodes WHERE id = ?')
+            .get(id);
+        return { ...this.rowToNode(row), seq };
+    }
+    getNode(id) {
+        const db = getDb();
+        const row = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id);
+        return row ? this.rowToNode(row) : null;
+    }
+    updateNode(id, input) {
+        const db = getDb();
+        // Get current state for revision
+        const current = this.getNode(id);
+        if (!current) {
+            throw new Error(`Node not found: ${id}`);
+        }
+        // Build revision
+        const revision = {
+            title: current.title,
+            trigger: current.trigger || undefined,
+            why: current.why || undefined,
+            understanding: current.understanding || undefined,
+            version: current.version,
+            timestamp: new Date().toISOString(),
+            revisionWhy: input.revisionWhy || 'Updated',
+            conversationId: input.conversationId || null,
+        };
+        const revisions = [...current.revisions, revision];
+        // Merge metadata if provided
+        let mergedMetadata = null;
+        if (input.metadata) {
+            const existingMetadata = current.metadata || {};
+            mergedMetadata = JSON.stringify({
+                ...existingMetadata,
+                ...input.metadata,
+            });
+        }
+        // Update
+        const stmt = db.prepare(`
+      UPDATE nodes SET
+        title = COALESCE(?, title),
+        trigger = COALESCE(?, trigger),
+        why = COALESCE(?, why),
+        understanding = COALESCE(?, understanding),
+        validated = CASE WHEN ? IS NOT NULL THEN ? ELSE validated END,
+        revisions = ?,
+        version = version + 1,
+        updated_at = datetime('now'),
+        content = COALESCE(?, content),
+        summary = COALESCE(?, summary),
+        level = COALESCE(?, level),
+        is_doc_root = CASE WHEN ? IS NOT NULL THEN ? ELSE is_doc_root END,
+        file_type = COALESCE(?, file_type),
+        "references" = COALESCE(?, "references"),
+        metadata = COALESCE(?, metadata)
+      WHERE id = ?
+    `);
+        const validatedVal = input.validated !== undefined ? (input.validated ? 1 : 0) : null;
+        const isDocRootVal = input.isDocRoot !== undefined ? (input.isDocRoot ? 1 : 0) : null;
+        stmt.run(input.title || null, input.trigger || null, input.why || null, input.understanding || null, validatedVal, validatedVal, JSON.stringify(revisions), input.content || null, input.summary || null, input.level || null, isDocRootVal, isDocRootVal, input.fileType || null, input.references ? JSON.stringify(input.references) : null, mergedMetadata, id);
+        const seq = logEvent('revised', 'node', id, input.conversationId || null, `Revised concept: ${input.title || current.title}`, { revisionWhy: input.revisionWhy });
+        this.markDirty();
+        const row = db
+            .prepare('SELECT * FROM nodes WHERE id = ?')
+            .get(id);
+        return { ...this.rowToNode(row), seq };
+    }
+    /**
+     * Add a reference to an existing node (appends to existing references)
+     */
+    addReference(nodeId, reference) {
+        const db = getDb();
+        const node = this.getNode(nodeId);
+        if (!node)
+            return null;
+        const existingRefs = node.references || [];
+        // Check for duplicates - by URL or by project+nodeId
+        const isDuplicate = existingRefs.some((r) => {
+            if (reference.url && r.url === reference.url)
+                return true;
+            if (reference.project &&
+                reference.nodeId &&
+                r.project === reference.project &&
+                r.nodeId === reference.nodeId)
+                return true;
+            return false;
+        });
+        if (isDuplicate) {
+            return node; // Already exists
+        }
+        const newRefs = [...existingRefs, reference];
+        db.prepare('UPDATE nodes SET "references" = ?, updated_at = datetime(\'now\') WHERE id = ?').run(JSON.stringify(newRefs), nodeId);
+        this.markDirty();
+        return this.getNode(nodeId);
+    }
+    /**
+     * Set metadata on a node (merges with existing metadata)
+     * Use this for module-specific data like narrative-engine coordinates
+     */
+    setMetadata(nodeId, metadata) {
+        const db = getDb();
+        const node = this.getNode(nodeId);
+        if (!node)
+            return null;
+        const existingMetadata = node.metadata || {};
+        const merged = { ...existingMetadata, ...metadata };
+        db.prepare("UPDATE nodes SET metadata = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(merged), nodeId);
+        this.markDirty();
+        return this.getNode(nodeId);
+    }
+    /**
+     * Get metadata from a node
+     */
+    getMetadata(nodeId) {
+        const node = this.getNode(nodeId);
+        if (!node)
+            return null;
+        return node.metadata || {};
+    }
+    /**
+     * Set a specific metadata key on a node
+     */
+    setMetadataKey(nodeId, key, value) {
+        return this.setMetadata(nodeId, { [key]: value });
+    }
+    /**
+     * Get a specific metadata key from a node
+     */
+    getMetadataKey(nodeId, key) {
+        const metadata = this.getMetadata(nodeId);
+        if (!metadata)
+            return null;
+        return metadata[key] ?? null;
+    }
+    /**
+     * Remove a metadata key from a node
+     */
+    removeMetadataKey(nodeId, key) {
+        const db = getDb();
+        const node = this.getNode(nodeId);
+        if (!node)
+            return null;
+        const existingMetadata = { ...(node.metadata || {}) };
+        delete existingMetadata[key];
+        db.prepare("UPDATE nodes SET metadata = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(existingMetadata), nodeId);
+        this.markDirty();
+        return this.getNode(nodeId);
+    }
+    archiveNode(id, reason, conversationId) {
+        const db = getDb();
+        const node = this.getNode(id);
+        if (!node)
+            return false;
+        db.prepare(`
+      UPDATE nodes SET active = 0, archived_at = datetime('now'), archive_reason = ?
+      WHERE id = ?
+    `).run(reason || null, id);
+        logEvent('archived', 'node', id, conversationId || null, `Archived: ${node.title}`);
+        this.markDirty();
+        return true;
+    }
+    /**
+     * Convert a document node to a concept node by clearing document-specific fields.
+     * Optionally moves content to understanding.
+     */
+    convertToConcept(id, options = {}) {
+        const db = getDb();
+        const current = this.getNode(id);
+        if (!current) {
+            throw new Error(`Node not found: ${id}`);
+        }
+        // Determine new understanding
+        let newUnderstanding = current.understanding;
+        if (options.moveContent && current.content && !current.understanding) {
+            newUnderstanding = current.content;
+        }
+        // Build revision
+        const revision = {
+            title: current.title,
+            trigger: current.trigger || undefined,
+            why: current.why || undefined,
+            understanding: current.understanding || undefined,
+            content: current.content || undefined,
+            version: current.version,
+            timestamp: new Date().toISOString(),
+            revisionWhy: options.why || 'Converted from document to concept node',
+            conversationId: options.conversationId || null,
+        };
+        const revisions = [...current.revisions, revision];
+        // Clear document fields, update trigger and understanding
+        const stmt = db.prepare(`
+      UPDATE nodes SET
+        content = NULL,
+        summary = NULL,
+        level = NULL,
+        is_doc_root = NULL,
+        file_type = NULL,
+        trigger = ?,
+        understanding = ?,
+        revisions = ?,
+        version = version + 1,
+        updated_at = datetime('now')
+      WHERE id = ?
+    `);
+        stmt.run(options.trigger || current.trigger || 'foundation', newUnderstanding || null, JSON.stringify(revisions), id);
+        const seq = logEvent('revised', 'node', id, options.conversationId || null, `Converted to concept: ${current.title}`);
+        this.markDirty();
+        const updated = this.getNode(id);
+        if (!updated) {
+            throw new Error(`Node not found after update: ${id}`);
+        }
+        return { ...updated, seq };
+    }
+    findNodeByName(name) {
+        const db = getDb();
+        const row = db
+            .prepare(`
+      SELECT * FROM nodes WHERE active = 1 AND LOWER(title) = LOWER(?)
+    `)
+            .get(name);
+        return row ? this.rowToNode(row) : null;
+    }
+    findSimilarNodes(name, limit = 5) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT * FROM nodes WHERE active = 1 AND LOWER(title) LIKE LOWER(?)
+      ORDER BY LENGTH(title) ASC LIMIT ?
+    `)
+            .all(`%${name}%`, limit);
+        return rows.map((r) => this.rowToNode(r));
+    }
+    // --------------------------------------------------------------------------
+    // Edge CRUD
+    // --------------------------------------------------------------------------
+    createEdge(input) {
+        const db = getDb();
+        const id = `e_${uuidv4().slice(0, 8)}`;
+        // Verify nodes exist to prevent FK constraint failure
+        const fromNode = this.getNode(input.fromId);
+        if (!fromNode) {
+            throw new Error(`Source node not found: "${input.fromId}". You must create the node first using graph_add_concept.`);
+        }
+        const toNode = this.getNode(input.toId);
+        if (!toNode) {
+            throw new Error(`Target node not found: "${input.toId}". You must create the node first using graph_add_concept.`);
+        }
+        // Validate edge type - ordered by category, 'relates' is LAST RESORT
+        const VALID_EDGE_TYPES = [
+            // Semantic - how ideas relate conceptually
+            'supersedes', // New understanding replaces old
+            'contradicts', // Creates tension (one must yield)
+            'diverse_from', // Different perspective (both valid)
+            'refines', // Adds precision to existing concept
+            'answers', // Resolves a question
+            'questions', // Raises doubt about a concept
+            'expresses', // Document → concept it discusses
+            'implements', // Abstract → concrete realization
+            'contextualizes', // Provides framing
+            // Epistemic - how knowledge was acquired
+            'learned_from', // Derived understanding from source
+            // Predictive - tracking forecasts
+            'validates', // Later evidence confirms a prediction
+            'invalidates', // Later evidence refutes a prediction
+            // Structural - document organization
+            'contains', // Parent → child
+            'next', // Sequence ordering
+            // LAST RESORT - only use if NONE of the above fit
+            'relates', // Avoid! Pick a specific type above
+        ];
+        if (!input.type) {
+            throw new Error(`Edge type is required. Pick one: ${VALID_EDGE_TYPES.slice(0, -1).join(', ')}. ` +
+                `(Use 'relates' ONLY if nothing else fits.) ` +
+                `Think: How does "${fromNode.title}" affect understanding of "${toNode.title}"?`);
+        }
+        if (!VALID_EDGE_TYPES.includes(input.type)) {
+            throw new Error(`Invalid edge type: "${input.type}". Valid types are: ${VALID_EDGE_TYPES.join(', ')}. ` +
+                `Do not invent edge types like "chosen as" or "considered for".`);
+        }
+        // Require why field for ALL edges - every connection is a cognitive decision
+        if (!input.why || input.why.trim().length < 3) {
+            throw new Error(`Edge requires a meaningful "why" field (min 3 chars). ` +
+                `Explain WHY "${fromNode.title}" ${input.type} "${toNode.title}". ` +
+                `Bad: "" or "connects". Good: "Relates to X".`);
+        }
+        const stmt = db.prepare(`
+      INSERT INTO edges (id, from_id, to_id, type, explanation, why, conversation_id, tool_call_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(id, input.fromId, input.toId, input.type || 'relates', input.explanation || null, input.why || null, input.conversationId, input.toolCallId ?? null);
+        const seq = logEvent('created', 'edge', id, input.conversationId, `Created edge: ${input.fromId} → ${input.toId}`);
+        this.markDirty();
+        const row = db
+            .prepare('SELECT * FROM edges WHERE id = ?')
+            .get(id);
+        return { ...this.rowToEdge(row), seq };
+    }
+    getEdge(id) {
+        const db = getDb();
+        const row = db.prepare('SELECT * FROM edges WHERE id = ?').get(id);
+        return row ? this.rowToEdge(row) : null;
+    }
+    getEdgesBetween(fromId, toId) {
+        const db = getDb();
+        const rows = db
+            .prepare('SELECT * FROM edges WHERE from_id = ? AND to_id = ? AND active = 1')
+            .all(fromId, toId);
+        return rows.map((row) => this.rowToEdge(row));
+    }
+    updateEdge(id, input) {
+        const db = getDb();
+        const current = this.getEdge(id);
+        if (!current) {
+            throw new Error(`Edge not found: ${id}`);
+        }
+        const revision = {
+            explanation: current.explanation || undefined,
+            why: current.why || undefined,
+            version: current.version,
+            timestamp: new Date().toISOString(),
+            revisionWhy: input.revisionWhy || 'Updated',
+            conversationId: input.conversationId || null,
+        };
+        const revisions = [...current.revisions, revision];
+        db.prepare(`
+      UPDATE edges SET
+        type = COALESCE(?, type),
+        explanation = COALESCE(?, explanation),
+        why = COALESCE(?, why),
+        revisions = ?,
+        version = version + 1,
+        updated_at = datetime('now')
+      WHERE id = ?
+    `).run(input.type || null, input.explanation || null, input.why || null, JSON.stringify(revisions), id);
+        const seq = logEvent('revised', 'edge', id, input.conversationId || null, `Revised edge: ${id}`);
+        this.markDirty();
+        const row = db
+            .prepare('SELECT * FROM edges WHERE id = ?')
+            .get(id);
+        return { ...this.rowToEdge(row), seq };
+    }
+    archiveEdge(id, conversationId) {
+        const db = getDb();
+        const edge = this.getEdge(id);
+        if (!edge)
+            return false;
+        db.prepare("UPDATE edges SET active = 0, updated_at = datetime('now') WHERE id = ?").run(id);
+        logEvent('archived', 'edge', id, conversationId || null, `Archived edge: ${id}`);
+        this.markDirty();
+        return true;
+    }
+    // --------------------------------------------------------------------------
+    // Full-text search
+    // --------------------------------------------------------------------------
+    searchNodes(query, limit = 20) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT n.* FROM nodes n
+      JOIN nodes_fts fts ON n.id = fts.id
+      WHERE nodes_fts MATCH ? AND n.active = 1
+      ORDER BY rank
+      LIMIT ?
+    `)
+            .all(query, limit);
+        return rows.map((r) => this.rowToNode(r));
+    }
+    // --------------------------------------------------------------------------
+    // Advanced queries using graphology
+    // --------------------------------------------------------------------------
+    /**
+     * Get all nodes within N hops of a given node
+     */
+    getNeighborhood(nodeId, depth = 2) {
+        const graph = this.getGraph();
+        if (!graph.hasNode(nodeId)) {
+            throw new Error(`Node not found: ${nodeId}`);
+        }
+        const visited = new Set();
+        const nodeIds = [];
+        bfsFromNode(graph, nodeId, (node, _attr, d) => {
+            if (d <= depth) {
+                visited.add(node);
+                nodeIds.push(node);
+                return false; // continue
+            }
+            return true; // stop this branch
+        });
+        const nodes = nodeIds
+            .map((id) => this.nodesCache.get(id))
+            .filter((n) => n !== undefined);
+        const edges = [];
+        // Collect edges between visited nodes
+        for (const nid of visited) {
+            graph.forEachOutEdge(nid, (_edge, attrs, _source, target) => {
+                if (visited.has(target)) {
+                    const edgeData = this.edgesCache.get(attrs.id);
+                    if (edgeData)
+                        edges.push(edgeData);
+                }
+            });
+        }
+        return { nodes, edges, center: nodeId, depth };
+    }
+    /**
+     * Find shortest path between two nodes
+     */
+    findPath(fromId, toId) {
+        const graph = this.getGraph();
+        if (!graph.hasNode(fromId) || !graph.hasNode(toId)) {
+            return { exists: false, path: null, pathNodes: [], length: 0 };
+        }
+        const path = bidirectional(graph, fromId, toId);
+        if (!path) {
+            return { exists: false, path: null, pathNodes: [], length: 0 };
+        }
+        const pathNodes = path
+            .map((id) => this.nodesCache.get(id))
+            .filter((n) => n !== undefined);
+        return {
+            exists: true,
+            path,
+            pathNodes,
+            length: path.length - 1,
+        };
+    }
+    /**
+     * Detect communities using Louvain algorithm
+     */
+    detectCommunities() {
+        const graph = this.getGraph();
+        // Louvain needs undirected graph
+        // biome-ignore lint/suspicious/noExplicitAny: graphology ESM/CJS compatibility
+        const undirected = new GraphConstructor({
+            type: 'undirected',
+        });
+        graph.forEachNode((node) => undirected.addNode(node));
+        graph.forEachEdge((_edge, _attrs, source, target) => {
+            if (!undirected.hasEdge(source, target)) {
+                undirected.addEdge(source, target);
+            }
+        });
+        // biome-ignore lint/suspicious/noExplicitAny: graphology-communities-louvain ESM/CJS compatibility
+        const communities = louvainFn(undirected);
+        const result = new Map();
+        for (const [nodeId, communityId] of Object.entries(communities)) {
+            if (!result.has(communityId)) {
+                result.set(communityId, []);
+            }
+            const node = this.nodesCache.get(nodeId);
+            if (node)
+                result.get(communityId)?.push(node);
+        }
+        // Calculate modularity - just return number of communities as proxy
+        const modularity = result.size > 0 ? 1 / result.size : 0;
+        return {
+            communities: result,
+            modularity,
+            nodeCount: graph.order,
+        };
+    }
+    /**
+     * Get importance scores using various centrality measures
+     */
+    getImportance() {
+        const graph = this.getGraph();
+        // Degree centrality - calculate manually
+        const degreeResults = [];
+        graph.forEachNode((id) => {
+            const node = this.nodesCache.get(id);
+            if (node) {
+                degreeResults.push({
+                    node,
+                    inDegree: graph.inDegree(id),
+                    outDegree: graph.outDegree(id),
+                    total: graph.degree(id),
+                });
+            }
+        });
+        degreeResults.sort((a, b) => b.total - a.total);
+        // Simplified betweenness - nodes that appear on many shortest paths
+        // For now, use degree as proxy (high-degree nodes tend to be on more paths)
+        const betweennessResults = degreeResults.map((r) => ({
+            node: r.node,
+            score: r.total / (graph.order || 1),
+        }));
+        // PageRank (simplified - using degree as proxy for now)
+        const pageRankResults = degreeResults.map((r) => ({
+            node: r.node,
+            score: r.total / (graph.order || 1),
+        }));
+        return {
+            pageRank: pageRankResults.slice(0, 20),
+            betweenness: betweennessResults.slice(0, 20),
+            degree: degreeResults.slice(0, 20),
+        };
+    }
+    /**
+     * Find structurally similar nodes (same neighbor patterns)
+     */
+    findSimilar(nodeId, limit = 10) {
+        const graph = this.getGraph();
+        if (!graph.hasNode(nodeId))
+            return [];
+        const neighbors = new Set(graph.neighbors(nodeId));
+        const results = [];
+        graph.forEachNode((otherId) => {
+            if (otherId === nodeId)
+                return;
+            const otherNeighbors = new Set(graph.neighbors(otherId));
+            const intersection = new Set([...neighbors].filter((n) => otherNeighbors.has(n)));
+            const union = new Set([...neighbors, ...otherNeighbors]);
+            const sharedNeighbors = intersection.size;
+            const jaccardSimilarity = union.size > 0 ? intersection.size / union.size : 0;
+            if (sharedNeighbors > 0) {
+                const node = this.nodesCache.get(otherId);
+                if (node) {
+                    results.push({
+                        node,
+                        sharedNeighbors,
+                        jaccardSimilarity,
+                    });
+                }
+            }
+        });
+        return results
+            .sort((a, b) => b.jaccardSimilarity - a.jaccardSimilarity)
+            .slice(0, limit);
+    }
+    /**
+     * Find semantic gaps - nodes that share keywords but aren't connected
+     */
+    findSemanticGaps(limit = 20) {
+        const graph = this.getGraph();
+        const gaps = [];
+        // Build term index
+        const nodeTerms = new Map();
+        this.nodesCache.forEach((node, id) => {
+            const text = `${node.title} ${node.understanding || ''}`.toLowerCase();
+            const terms = new Set(text.split(/\W+/).filter((t) => t.length > 3));
+            nodeTerms.set(id, terms);
+        });
+        // Find pairs with shared terms but no connection
+        const nodeIds = Array.from(this.nodesCache.keys());
+        for (let i = 0; i < nodeIds.length; i++) {
+            for (let j = i + 1; j < nodeIds.length; j++) {
+                const id1 = nodeIds[i];
+                const id2 = nodeIds[j];
+                const terms1 = nodeTerms.get(id1);
+                const terms2 = nodeTerms.get(id2);
+                if (!terms1 || !terms2)
+                    continue;
+                const shared = [...terms1].filter((t) => terms2.has(t));
+                if (shared.length >= 2) {
+                    const connected = graph.hasEdge(id1, id2) || graph.hasEdge(id2, id1);
+                    if (!connected) {
+                        const node1 = this.nodesCache.get(id1);
+                        const node2 = this.nodesCache.get(id2);
+                        if (node1 && node2) {
+                            gaps.push({
+                                node1,
+                                node2,
+                                sharedTerms: shared,
+                                connected: false,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        return gaps
+            .sort((a, b) => b.sharedTerms.length - a.sharedTerms.length)
+            .slice(0, limit);
+    }
+    /**
+     * Get all nodes and edges (for context building)
+     */
+    getAll() {
+        const db = getDb();
+        const nodeRows = db
+            .prepare('SELECT * FROM nodes WHERE active = 1')
+            .all();
+        const edgeRows = db
+            .prepare('SELECT * FROM edges WHERE active = 1')
+            .all();
+        return {
+            nodes: nodeRows.map((r) => this.rowToNode(r)),
+            edges: edgeRows.map((r) => this.rowToEdge(r)),
+        };
+    }
+    /**
+     * Get all nodes and edges including superseded (inactive) nodes
+     * Superseded nodes are those that have an incoming 'supersedes' edge
+     */
+    getAllWithSuperseded() {
+        const db = getDb();
+        // Get all active edges first
+        const edgeRows = db
+            .prepare('SELECT * FROM edges WHERE active = 1')
+            .all();
+        const edges = edgeRows.map((r) => this.rowToEdge(r));
+        // Find nodes that are superseded (have incoming supersedes edge)
+        const supersededNodeIds = new Set(edges.filter((e) => e.type === 'supersedes').map((e) => e.toId));
+        // Get active nodes
+        const activeNodeRows = db
+            .prepare('SELECT * FROM nodes WHERE active = 1')
+            .all();
+        const activeNodes = activeNodeRows.map((r) => this.rowToNode(r));
+        // Get inactive nodes that are superseded (they were archived when superseded)
+        const supersededIds = Array.from(supersededNodeIds);
+        let inactiveSupersededNodes = [];
+        if (supersededIds.length > 0) {
+            const placeholders = supersededIds.map(() => '?').join(',');
+            const inactiveRows = db
+                .prepare(`SELECT * FROM nodes WHERE active = 0 AND id IN (${placeholders})`)
+                .all(...supersededIds);
+            inactiveSupersededNodes = inactiveRows.map((r) => this.rowToNode(r));
+        }
+        return {
+            nodes: [...activeNodes, ...inactiveSupersededNodes],
+            edges,
+            supersededNodeIds,
+        };
+    }
+    /**
+     * Get random nodes for serendipity
+     */
+    getRandomNodes(count) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT * FROM nodes WHERE active = 1 ORDER BY RANDOM() LIMIT ?
+    `)
+            .all(count);
+        return rows.map((r) => this.rowToNode(r));
+    }
+    /**
+     * Get random edges for serendipity
+     */
+    getRandomEdges(count) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT * FROM edges WHERE active = 1 ORDER BY RANDOM() LIMIT ?
+    `)
+            .all(count);
+        return rows.map((r) => this.rowToEdge(r));
+    }
+    /**
+     * Question-focused serendipity: pair open questions with random nodes
+     * This preserves true randomness while directing it toward receptive targets (questions seeking answers)
+     */
+    questionSerendipity(options = {}) {
+        const { questionsLimit = 5, randomPerQuestion = 3 } = options;
+        const db = getDb();
+        // Get open questions (nodes with trigger = 'question')
+        const questionRows = db
+            .prepare(`
+      SELECT * FROM nodes
+      WHERE active = 1 AND trigger = 'question'
+      ORDER BY RANDOM()
+      LIMIT ?
+    `)
+            .all(questionsLimit);
+        const questions = questionRows.map((r) => this.rowToNode(r));
+        if (questions.length === 0) {
+            return [];
+        }
+        // For each question, get random nodes (excluding the question itself)
+        const results = [];
+        for (const question of questions) {
+            const randomRows = db
+                .prepare(`
+        SELECT * FROM nodes
+        WHERE active = 1 AND id != ? AND trigger != 'question'
+        ORDER BY RANDOM()
+        LIMIT ?
+      `)
+                .all(question.id, randomPerQuestion);
+            const randomNodes = randomRows.map((r) => this.rowToNode(r));
+            if (randomNodes.length > 0) {
+                results.push({ question, randomNodes });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get supersession chain for a node
+     */
+    getEvolutionChain(nodeId) {
+        const db = getDb();
+        const chain = [];
+        let currentId = nodeId;
+        // Walk backwards through supersession edges
+        while (currentId) {
+            const node = this.getNode(currentId);
+            if (node)
+                chain.unshift(node);
+            // Find what this node supersedes
+            const supersedes = db
+                .prepare(`
+        SELECT to_id FROM edges
+        WHERE from_id = ? AND type = 'supersedes' AND active = 1
+      `)
+                .get(currentId);
+            currentId = supersedes?.to_id || null;
+        }
+        // Also walk forward to find what supersedes this node
+        currentId = nodeId;
+        while (currentId) {
+            const supersededBy = db
+                .prepare(`
+        SELECT from_id FROM edges
+        WHERE to_id = ? AND type = 'supersedes' AND active = 1
+      `)
+                .get(currentId);
+            if (supersededBy) {
+                const node = this.getNode(supersededBy.from_id);
+                if (node)
+                    chain.push(node);
+                currentId = supersededBy.from_id;
+            }
+            else {
+                currentId = null;
+            }
+        }
+        return chain;
+    }
+    /**
+     * Suggest potential bridges - nodes that would connect disconnected clusters
+     */
+    suggestBridges(limit = 10) {
+        const graph = this.getGraph();
+        const suggestions = [];
+        // Find nodes with no path between them
+        const nodeIds = Array.from(this.nodesCache.keys());
+        for (let i = 0; i < Math.min(nodeIds.length, 50); i++) {
+            for (let j = i + 1; j < Math.min(nodeIds.length, 50); j++) {
+                const id1 = nodeIds[i];
+                const id2 = nodeIds[j];
+                const path = bidirectional(graph, id1, id2);
+                if (!path) {
+                    // These nodes aren't connected - connecting them would bridge clusters
+                    const node1 = this.nodesCache.get(id1);
+                    const node2 = this.nodesCache.get(id2);
+                    if (node1 && node2) {
+                        suggestions.push({
+                            node1,
+                            node2,
+                            wouldConnect: graph.neighbors(id1).length + graph.neighbors(id2).length,
+                        });
+                    }
+                }
+            }
+        }
+        return suggestions
+            .sort((a, b) => b.wouldConnect - a.wouldConnect)
+            .slice(0, limit);
+    }
+    // --------------------------------------------------------------------------
+    // Embedding and Semantic Search
+    // --------------------------------------------------------------------------
+    /**
+     * Generate and store embedding for a node
+     * Call this after creating a node to enable semantic search
+     */
+    async generateAndStoreEmbedding(nodeId) {
+        const db = getDb();
+        const node = this.getNode(nodeId);
+        if (!node)
+            return false;
+        try {
+            const embedding = await generateNodeEmbedding({
+                title: node.title,
+                understanding: node.understanding,
+                why: node.why,
+            });
+            const buffer = embeddingToBuffer(embedding);
+            db.prepare('UPDATE nodes SET embedding = ? WHERE id = ?').run(buffer, nodeId);
+            this.markDirty();
+            return true;
+        }
+        catch (error) {
+            console.error(`[GraphStore] Failed to generate embedding for ${nodeId}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Generate embeddings for all nodes that don't have them
+     * Returns count of nodes processed
+     */
+    async backfillEmbeddings(onProgress) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT id FROM nodes WHERE active = 1 AND embedding IS NULL
+    `)
+            .all();
+        let processed = 0;
+        for (const row of rows) {
+            await this.generateAndStoreEmbedding(row.id);
+            processed++;
+            if (onProgress)
+                onProgress(processed, rows.length);
+        }
+        return processed;
+    }
+    /**
+     * Semantic search: find nodes similar to a query string
+     */
+    async semanticSearch(query, limit = 10) {
+        const db = getDb();
+        // Generate embedding for query
+        const queryEmbedding = await generateEmbedding(query);
+        // Get all nodes with embeddings
+        const rows = db
+            .prepare(`
+      SELECT * FROM nodes WHERE active = 1 AND embedding IS NOT NULL
+    `)
+            .all();
+        // Score by cosine similarity
+        const results = [];
+        for (const row of rows) {
+            const node = this.rowToNode(row);
+            if (node.embedding) {
+                const similarity = cosineSimilarity(queryEmbedding, node.embedding);
+                results.push({ node, similarity });
+            }
+        }
+        // Sort by similarity descending
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, limit);
+    }
+    /**
+     * Find semantic gaps using embedding similarity
+     * Finds node pairs that are semantically similar but not connected
+     */
+    findSemanticGapsWithEmbeddings(limit = 20, minSimilarity = 0.5) {
+        const graph = this.getGraph();
+        const gaps = [];
+        // Get nodes with embeddings
+        const nodesWithEmbeddings = Array.from(this.nodesCache.values()).filter((n) => n.embedding !== null);
+        // Compare all pairs
+        for (let i = 0; i < nodesWithEmbeddings.length; i++) {
+            for (let j = i + 1; j < nodesWithEmbeddings.length; j++) {
+                const node1 = nodesWithEmbeddings[i];
+                const node2 = nodesWithEmbeddings[j];
+                // Skip if already connected
+                if (graph.hasEdge(node1.id, node2.id) ||
+                    graph.hasEdge(node2.id, node1.id)) {
+                    continue;
+                }
+                // Calculate similarity (embeddings are guaranteed non-null by filter above)
+                const emb1 = node1.embedding;
+                const emb2 = node2.embedding;
+                if (!emb1 || !emb2)
+                    continue;
+                const similarity = cosineSimilarity(emb1, emb2);
+                if (similarity >= minSimilarity) {
+                    gaps.push({
+                        node1,
+                        node2,
+                        sharedTerms: [], // Not using keyword matching in this version
+                        embeddingSimilarity: similarity,
+                        connected: false,
+                    });
+                }
+            }
+        }
+        // Sort by similarity descending
+        gaps.sort((a, b) => (b.embeddingSimilarity || 0) - (a.embeddingSimilarity || 0));
+        return gaps.slice(0, limit);
+    }
+    /**
+     * Get embedding coverage stats
+     */
+    getEmbeddingStats() {
+        const db = getDb();
+        const total = db
+            .prepare('SELECT COUNT(*) as count FROM nodes WHERE active = 1')
+            .get().count;
+        const withEmbedding = db
+            .prepare('SELECT COUNT(*) as count FROM nodes WHERE active = 1 AND embedding IS NOT NULL')
+            .get().count;
+        return {
+            total,
+            withEmbedding,
+            coverage: total > 0 ? withEmbedding / total : 0,
+        };
+    }
+    // ==================== Temporal Tracking ====================
+    /**
+     * Record an access to a node (increments access_count, updates last_accessed)
+     */
+    recordAccess(nodeId) {
+        const db = getDb();
+        db.prepare(`
+      UPDATE nodes
+      SET access_count = COALESCE(access_count, 0) + 1,
+          last_accessed = datetime('now')
+      WHERE id = ?
+    `).run(nodeId);
+    }
+    /**
+     * Record access to multiple nodes at once
+     */
+    recordAccessBatch(nodeIds) {
+        const db = getDb();
+        const stmt = db.prepare(`
+      UPDATE nodes
+      SET access_count = COALESCE(access_count, 0) + 1,
+          last_accessed = datetime('now')
+      WHERE id = ?
+    `);
+        for (const id of nodeIds) {
+            stmt.run(id);
+        }
+    }
+    /**
+     * Calculate temperature for a node (0-1 scale)
+     * Temperature combines recency and frequency of access
+     * Higher = hotter (more recently/frequently accessed)
+     */
+    getNodeTemperature(nodeId) {
+        const db = getDb();
+        const row = db
+            .prepare(`
+      SELECT
+        access_count,
+        last_accessed,
+        created_at
+      FROM nodes WHERE id = ? AND active = 1
+    `)
+            .get(nodeId);
+        if (!row)
+            return 0;
+        const accessCount = row.access_count || 0;
+        const lastAccessed = row.last_accessed
+            ? new Date(row.last_accessed)
+            : new Date(row.created_at);
+        const now = new Date();
+        // Recency score: exponential decay with half-life of 7 days
+        const daysSinceAccess = (now.getTime() - lastAccessed.getTime()) / (1000 * 60 * 60 * 24);
+        const halfLifeDays = 7;
+        const recencyScore = Math.exp((-daysSinceAccess * Math.LN2) / halfLifeDays);
+        // Frequency score: logarithmic scaling (diminishing returns on high access)
+        const frequencyScore = Math.log10(accessCount + 1) / Math.log10(100); // Normalized to ~1 at 100 accesses
+        // Combined temperature: 70% recency, 30% frequency
+        const temperature = 0.7 * recencyScore + 0.3 * Math.min(frequencyScore, 1);
+        return Math.round(temperature * 1000) / 1000;
+    }
+    /**
+     * Get all nodes ranked by temperature (hottest first)
+     */
+    getTemperatureRanking(limit = 50) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT * FROM nodes WHERE active = 1
+    `)
+            .all();
+        const ranked = rows.map((row) => {
+            const node = this.rowToNode(row);
+            return {
+                node,
+                temperature: this.getNodeTemperature(node.id),
+            };
+        });
+        ranked.sort((a, b) => b.temperature - a.temperature);
+        return ranked.slice(0, limit);
+    }
+    /**
+     * Get cold nodes - least accessed, candidates for serendipity or review
+     */
+    getColdNodes(limit = 20) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+      SELECT *,
+        COALESCE(access_count, 0) as access_count,
+        COALESCE(last_accessed, created_at) as effective_last_accessed
+      FROM nodes
+      WHERE active = 1
+      ORDER BY access_count ASC, effective_last_accessed ASC
+      LIMIT ?
+    `)
+            .all(limit);
+        const now = new Date();
+        return rows.map((row) => {
+            const node = this.rowToNode(row);
+            const lastAccessed = row.last_accessed || row.created_at;
+            const daysSinceAccess = Math.round((now.getTime() - new Date(lastAccessed).getTime()) /
+                (1000 * 60 * 60 * 24));
+            return {
+                node,
+                temperature: this.getNodeTemperature(node.id),
+                daysSinceAccess,
+            };
+        });
+    }
+    /**
+     * Get hot nodes - most recently/frequently accessed
+     */
+    getHotNodes(limit = 20) {
+        const ranked = this.getTemperatureRanking(limit);
+        const db = getDb();
+        return ranked.map(({ node, temperature }) => {
+            const row = db
+                .prepare('SELECT access_count FROM nodes WHERE id = ?')
+                .get(node.id);
+            return {
+                node,
+                temperature,
+                accessCount: row?.access_count || 0,
+            };
+        });
+    }
+    /**
+     * Get temporal stats for the graph
+     */
+    getTemporalStats() {
+        const db = getDb();
+        const totalNodes = db
+            .prepare('SELECT COUNT(*) as count FROM nodes WHERE active = 1')
+            .get().count;
+        const accessedNodes = db
+            .prepare('SELECT COUNT(*) as count FROM nodes WHERE active = 1 AND access_count > 0')
+            .get().count;
+        const ranking = this.getTemperatureRanking(totalNodes);
+        const avgTemperature = ranking.length > 0
+            ? Math.round((ranking.reduce((sum, r) => sum + r.temperature, 0) /
+                ranking.length) *
+                1000) / 1000
+            : 0;
+        const hottest = ranking[0] || null;
+        const coldest = ranking[ranking.length - 1] || null;
+        return {
+            totalNodes,
+            accessedNodes,
+            neverAccessed: totalNodes - accessedNodes,
+            avgTemperature,
+            hottestNode: hottest
+                ? {
+                    id: hottest.node.id,
+                    name: hottest.node.title,
+                    temperature: hottest.temperature,
+                }
+                : null,
+            coldestNode: coldest
+                ? {
+                    id: coldest.node.id,
+                    name: coldest.node.title,
+                    temperature: coldest.temperature,
+                }
+                : null,
+        };
+    }
+    // ==================== Link Prediction ====================
+    /**
+     * Get neighbors of a node (both directions)
+     */
+    getNeighbors(nodeId) {
+        const db = getDb();
+        const outgoing = db
+            .prepare(`
+      SELECT to_id FROM edges WHERE from_id = ? AND active = 1
+    `)
+            .all(nodeId);
+        const incoming = db
+            .prepare(`
+      SELECT from_id FROM edges WHERE to_id = ? AND active = 1
+    `)
+            .all(nodeId);
+        const neighbors = new Set();
+        for (const r of outgoing) {
+            neighbors.add(r.to_id);
+        }
+        for (const r of incoming) {
+            neighbors.add(r.from_id);
+        }
+        return neighbors;
+    }
+    /**
+     * Check if two nodes are connected
+     */
+    areConnected(nodeId1, nodeId2) {
+        const db = getDb();
+        const edge = db
+            .prepare(`
+      SELECT id FROM edges
+      WHERE ((from_id = ? AND to_id = ?) OR (from_id = ? AND to_id = ?))
+      AND active = 1
+    `)
+            .get(nodeId1, nodeId2, nodeId2, nodeId1);
+        return !!edge;
+    }
+    /**
+     * Common Neighbors score - count of shared neighbors
+     */
+    commonNeighborsScore(nodeId1, nodeId2) {
+        const neighbors1 = this.getNeighbors(nodeId1);
+        const neighbors2 = this.getNeighbors(nodeId2);
+        let count = 0;
+        neighbors1.forEach((n) => {
+            if (neighbors2.has(n))
+                count++;
+        });
+        return count;
+    }
+    /**
+     * Jaccard similarity - shared neighbors / total unique neighbors
+     */
+    jaccardScore(nodeId1, nodeId2) {
+        const neighbors1 = this.getNeighbors(nodeId1);
+        const neighbors2 = this.getNeighbors(nodeId2);
+        let intersection = 0;
+        neighbors1.forEach((n) => {
+            if (neighbors2.has(n))
+                intersection++;
+        });
+        const union = new Set([...neighbors1, ...neighbors2]).size;
+        return union > 0 ? intersection / union : 0;
+    }
+    /**
+     * Adamic-Adar score - weighted by inverse log degree of shared neighbors
+     * Rare shared neighbors count more than common hubs
+     */
+    adamicAdarScore(nodeId1, nodeId2) {
+        const neighbors1 = this.getNeighbors(nodeId1);
+        const neighbors2 = this.getNeighbors(nodeId2);
+        let score = 0;
+        neighbors1.forEach((n) => {
+            if (neighbors2.has(n)) {
+                const neighborDegree = this.getNeighbors(n).size;
+                if (neighborDegree > 1) {
+                    score += 1 / Math.log(neighborDegree);
+                }
+            }
+        });
+        return score;
+    }
+    /**
+     * Preferential Attachment score - product of degrees
+     * Nodes with many connections tend to form more connections
+     */
+    preferentialAttachmentScore(nodeId1, nodeId2) {
+        const degree1 = this.getNeighbors(nodeId1).size;
+        const degree2 = this.getNeighbors(nodeId2).size;
+        return degree1 * degree2;
+    }
+    /**
+     * Combined link prediction score
+     * Normalizes and combines multiple signals
+     */
+    linkPredictionScore(nodeId1, nodeId2) {
+        const cn = this.commonNeighborsScore(nodeId1, nodeId2);
+        const jac = this.jaccardScore(nodeId1, nodeId2);
+        const aa = this.adamicAdarScore(nodeId1, nodeId2);
+        const pa = this.preferentialAttachmentScore(nodeId1, nodeId2);
+        // Normalize preferential attachment (can be very large)
+        const paMax = 400; // Assume max degree ~20 each
+        const paNorm = Math.min(pa / paMax, 1);
+        // Combined score: weight Adamic-Adar highest (best for novelty)
+        const combined = 0.4 * Math.min(aa / 3, 1) +
+            0.3 * jac +
+            0.2 * Math.min(cn / 5, 1) +
+            0.1 * paNorm;
+        return {
+            commonNeighbors: cn,
+            jaccard: Math.round(jac * 1000) / 1000,
+            adamicAdar: Math.round(aa * 1000) / 1000,
+            preferentialAttachment: pa,
+            combined: Math.round(combined * 1000) / 1000,
+        };
+    }
+    /**
+     * Suggest edges to create based on link prediction + embedding similarity
+     * Returns pairs that are structurally likely to connect but don't yet have an edge
+     */
+    async suggestEdges(limit = 20) {
+        const db = getDb();
+        const nodes = db
+            .prepare('SELECT * FROM nodes WHERE active = 1')
+            .all();
+        const nodeList = nodes.map((r) => this.rowToNode(r));
+        // Check embedding coverage
+        const embeddingStats = this.getEmbeddingStats();
+        const hasEmbeddings = embeddingStats.coverage > 0.5;
+        const suggestions = [];
+        // Compare all pairs (O(n²) but n is typically small for understanding graphs)
+        for (let i = 0; i < nodeList.length; i++) {
+            for (let j = i + 1; j < nodeList.length; j++) {
+                const node1 = nodeList[i];
+                const node2 = nodeList[j];
+                // Skip if already connected
+                if (this.areConnected(node1.id, node2.id))
+                    continue;
+                // Calculate structural score
+                const linkScore = this.linkPredictionScore(node1.id, node2.id);
+                // Skip if no structural signal at all
+                if (linkScore.combined < 0.05)
+                    continue;
+                // Calculate embedding similarity if available
+                let embeddingScore = null;
+                if (hasEmbeddings && node1.embedding && node2.embedding) {
+                    embeddingScore = cosineSimilarity(node1.embedding, node2.embedding);
+                }
+                // Calculate novelty score
+                // High novelty = high embedding distance (surprising connection) + structural support
+                let noveltyScore;
+                let reason;
+                if (embeddingScore !== null) {
+                    // Embedding distance (1 - similarity) indicates novelty
+                    const embeddingDistance = 1 - embeddingScore;
+                    if (embeddingDistance > 0.5 && linkScore.combined > 0.2) {
+                        // High novelty: structurally supported but semantically distant
+                        noveltyScore = 0.6 * embeddingDistance + 0.4 * linkScore.combined;
+                        reason =
+                            'Surprising bridge - semantically distant but structurally connected';
+                    }
+                    else if (embeddingScore > 0.6 && linkScore.combined > 0.1) {
+                        // Low novelty but likely valid: semantically similar with some structure
+                        noveltyScore = 0.3 * embeddingScore + 0.3 * linkScore.combined;
+                        reason =
+                            'Likely valid - semantically similar with structural support';
+                    }
+                    else {
+                        // Mixed signal
+                        noveltyScore = 0.5 * linkScore.combined;
+                        reason = 'Structural pattern suggests connection';
+                    }
+                }
+                else {
+                    // No embeddings, use structural score only
+                    noveltyScore = linkScore.combined;
+                    reason = `Structural: ${linkScore.commonNeighbors} shared neighbors`;
+                }
+                suggestions.push({
+                    node1,
+                    node2,
+                    structuralScore: linkScore.combined,
+                    embeddingScore: embeddingScore !== null
+                        ? Math.round(embeddingScore * 1000) / 1000
+                        : null,
+                    noveltyScore: Math.round(noveltyScore * 1000) / 1000,
+                    reason,
+                });
+            }
+        }
+        // Sort by novelty score (highest first)
+        suggestions.sort((a, b) => b.noveltyScore - a.noveltyScore);
+        return suggestions.slice(0, limit);
+    }
+    /**
+     * Get link prediction stats for a specific node
+     * Shows what edges this node might want to form
+     */
+    async suggestEdgesForNode(nodeId, limit = 10) {
+        const node = this.getNode(nodeId);
+        if (!node)
+            return [];
+        const db = getDb();
+        const otherNodes = db
+            .prepare('SELECT * FROM nodes WHERE active = 1 AND id != ?')
+            .all(nodeId);
+        const embeddingStats = this.getEmbeddingStats();
+        const hasEmbeddings = embeddingStats.coverage > 0.5;
+        const suggestions = [];
+        for (const row of otherNodes) {
+            const target = this.rowToNode(row);
+            // Skip if already connected
+            if (this.areConnected(nodeId, target.id))
+                continue;
+            const linkScore = this.linkPredictionScore(nodeId, target.id);
+            if (linkScore.combined < 0.05)
+                continue;
+            let embeddingScore = null;
+            if (hasEmbeddings && node.embedding && target.embedding) {
+                embeddingScore = cosineSimilarity(node.embedding, target.embedding);
+            }
+            let noveltyScore;
+            let reason;
+            if (embeddingScore !== null) {
+                const embeddingDistance = 1 - embeddingScore;
+                if (embeddingDistance > 0.5 && linkScore.combined > 0.2) {
+                    noveltyScore = 0.6 * embeddingDistance + 0.4 * linkScore.combined;
+                    reason = 'Surprising bridge';
+                }
+                else if (embeddingScore > 0.6) {
+                    noveltyScore = 0.3 * embeddingScore + 0.3 * linkScore.combined;
+                    reason = 'Semantically similar';
+                }
+                else {
+                    noveltyScore = 0.5 * linkScore.combined;
+                    reason = 'Structural pattern';
+                }
+            }
+            else {
+                noveltyScore = linkScore.combined;
+                reason = `${linkScore.commonNeighbors} shared neighbors`;
+            }
+            suggestions.push({
+                target,
+                structuralScore: linkScore.combined,
+                embeddingScore: embeddingScore !== null
+                    ? Math.round(embeddingScore * 1000) / 1000
+                    : null,
+                noveltyScore: Math.round(noveltyScore * 1000) / 1000,
+                reason,
+            });
+        }
+        suggestions.sort((a, b) => b.noveltyScore - a.noveltyScore);
+        return suggestions.slice(0, limit);
+    }
+    // ============================================================================
+    // Spreading Activation
+    // ============================================================================
+    /**
+     * Spreading activation from seed nodes
+     * Returns nodes ranked by accumulated activation energy
+     */
+    spreadingActivation(seedIds, options = {}) {
+        const { decayFactor = 0.5, maxSteps = 3, initialEnergy = 1.0, temperatureWeighted = true, } = options;
+        const activation = new Map();
+        // Initialize seeds
+        for (const seedId of seedIds) {
+            const seedNode = this.getNode(seedId);
+            if (!seedNode)
+                continue;
+            let energy = initialEnergy;
+            if (temperatureWeighted) {
+                const temp = this.getNodeTemperature(seedId);
+                // Cold nodes get boosted (more interesting to activate)
+                energy *= 1 + (1 - temp);
+            }
+            activation.set(seedId, { energy, pathLength: 0, source: seedId });
+        }
+        // Spread activation
+        for (let step = 0; step < maxSteps; step++) {
+            const currentNodes = Array.from(activation.entries()).filter(([, data]) => data.pathLength === step);
+            for (const [nodeId, data] of currentNodes) {
+                const neighbors = this.graph.neighbors(nodeId);
+                const spreadEnergy = (data.energy * decayFactor) / Math.max(neighbors.length, 1);
+                for (const neighborId of neighbors) {
+                    const existing = activation.get(neighborId);
+                    const newPathLength = step + 1;
+                    if (!existing) {
+                        let neighborEnergy = spreadEnergy;
+                        if (temperatureWeighted) {
+                            const temp = this.getNodeTemperature(neighborId);
+                            neighborEnergy *= 1 + (1 - temp);
+                        }
+                        activation.set(neighborId, {
+                            energy: neighborEnergy,
+                            pathLength: newPathLength,
+                            source: data.source,
+                        });
+                    }
+                    else if (existing.pathLength > newPathLength) {
+                        // Found shorter path
+                        existing.energy += spreadEnergy;
+                        existing.pathLength = newPathLength;
+                    }
+                    else {
+                        // Accumulate energy from multiple paths
+                        existing.energy += spreadEnergy * 0.5;
+                    }
+                }
+            }
+        }
+        // Convert to result array (excluding seeds)
+        const results = [];
+        for (const [nodeId, data] of activation) {
+            if (seedIds.includes(nodeId))
+                continue;
+            const node = this.getNode(nodeId);
+            if (node) {
+                results.push({
+                    node,
+                    activation: Math.round(data.energy * 1000) / 1000,
+                    pathLength: data.pathLength,
+                    source: data.source,
+                });
+            }
+        }
+        return results.sort((a, b) => b.activation - a.activation);
+    }
+    // ============================================================================
+    // Information Theory Scoring
+    // ============================================================================
+    /**
+     * Compute information gain (surprisal) of connecting two nodes
+     * Higher = more surprising/novel connection
+     */
+    informationGain(nodeId1, nodeId2) {
+        const node1 = this.getNode(nodeId1);
+        const node2 = this.getNode(nodeId2);
+        if (!node1 || !node2) {
+            return {
+                structuralSurprisal: 0,
+                semanticSurprisal: null,
+                clusterSurprisal: 0,
+                combined: 0,
+            };
+        }
+        // Structural surprisal: inverse of link prediction score
+        // Low prediction = high surprisal
+        const linkScore = this.linkPredictionScore(nodeId1, nodeId2);
+        const structuralSurprisal = 1 - linkScore.combined;
+        // Semantic surprisal: inverse of embedding similarity
+        let semanticSurprisal = null;
+        if (node1.embedding && node2.embedding) {
+            const similarity = cosineSimilarity(node1.embedding, node2.embedding);
+            semanticSurprisal = 1 - similarity;
+        }
+        // Cluster surprisal: are they in different communities?
+        const communityResult = this.detectCommunities();
+        let comm1;
+        let comm2;
+        for (const [commId, nodes] of communityResult.communities) {
+            if (nodes.some((n) => n.id === nodeId1))
+                comm1 = commId;
+            if (nodes.some((n) => n.id === nodeId2))
+                comm2 = commId;
+            if (comm1 !== undefined && comm2 !== undefined)
+                break;
+        }
+        const clusterSurprisal = comm1 !== comm2 ? 1.0 : 0.0;
+        // Combined score
+        let combined;
+        if (semanticSurprisal !== null) {
+            // Novel = structurally close but semantically distant
+            // This is "surprising bridge" territory
+            combined =
+                structuralSurprisal * 0.3 +
+                    semanticSurprisal * 0.4 +
+                    clusterSurprisal * 0.3;
+        }
+        else {
+            combined = structuralSurprisal * 0.5 + clusterSurprisal * 0.5;
+        }
+        return {
+            structuralSurprisal: Math.round(structuralSurprisal * 1000) / 1000,
+            semanticSurprisal: semanticSurprisal !== null
+                ? Math.round(semanticSurprisal * 1000) / 1000
+                : null,
+            clusterSurprisal,
+            combined: Math.round(combined * 1000) / 1000,
+        };
+    }
+    // ============================================================================
+    // Unified Serendipity Engine
+    // ============================================================================
+    /**
+     * Unified serendipity discovery - combines all algorithms
+     * Returns candidate connections ranked by serendipitous potential
+     */
+    async unifiedSerendipity(options = {}) {
+        const { limit = 10, seedStrategy = 'mixed', numSeeds = 3 } = options;
+        // Step 1: Select seeds based on strategy
+        const seeds = [];
+        const { nodes: allNodes } = this.getAll();
+        if (allNodes.length < 2) {
+            return [];
+        }
+        switch (seedStrategy) {
+            case 'hot': {
+                const hot = this.getHotNodes(numSeeds);
+                seeds.push(...hot.map((h) => h.node.id));
+                break;
+            }
+            case 'cold': {
+                const cold = this.getColdNodes(numSeeds);
+                seeds.push(...cold.map((c) => c.node.id));
+                break;
+            }
+            case 'random': {
+                const random = this.getRandomNodes(numSeeds);
+                seeds.push(...random.map((n) => n.id));
+                break;
+            }
+            case 'bridge': {
+                // Select nodes with high betweenness centrality
+                const importance = this.getImportance();
+                seeds.push(...importance.betweenness.slice(0, numSeeds).map((b) => b.node.id));
+                break;
+            }
+            default: {
+                // Mix of strategies: pick from different clusters
+                const communityResult = this.detectCommunities();
+                const clusterNodeIds = [];
+                for (const [, nodes] of communityResult.communities) {
+                    clusterNodeIds.push(nodes.map((n) => n.id));
+                }
+                if (clusterNodeIds.length >= 2) {
+                    // Pick from different clusters
+                    for (let i = 0; i < Math.min(numSeeds, clusterNodeIds.length); i++) {
+                        const clusterMembers = clusterNodeIds[i];
+                        const randomIdx = Math.floor(Math.random() * clusterMembers.length);
+                        seeds.push(clusterMembers[randomIdx]);
+                    }
+                }
+                else {
+                    // Single cluster - mix hot/cold/random
+                    const hot = this.getHotNodes(1);
+                    const cold = this.getColdNodes(1);
+                    const random = this.getRandomNodes(1);
+                    if (hot.length)
+                        seeds.push(hot[0].node.id);
+                    if (cold.length && !seeds.includes(cold[0].node.id))
+                        seeds.push(cold[0].node.id);
+                    if (random.length && !seeds.includes(random[0].id))
+                        seeds.push(random[0].id);
+                }
+                break;
+            }
+        }
+        if (seeds.length === 0) {
+            return [];
+        }
+        // Step 2: Spreading activation from seeds
+        const activated = this.spreadingActivation(seeds, {
+            decayFactor: 0.6,
+            maxSteps: 3,
+            temperatureWeighted: true,
+        });
+        // Step 3: Find candidate pairs
+        const candidates = new Map();
+        // Add pairs from spreading activation (activated nodes that aren't connected)
+        for (const act of activated.slice(0, 20)) {
+            for (const other of activated.slice(0, 20)) {
+                if (act.node.id >= other.node.id)
+                    continue; // Avoid duplicates
+                if (this.graph.hasEdge(act.node.id, other.node.id))
+                    continue;
+                if (this.graph.hasEdge(other.node.id, act.node.id))
+                    continue;
+                const key = `${act.node.id}:${other.node.id}`;
+                if (!candidates.has(key)) {
+                    candidates.set(key, {
+                        node1: act.node,
+                        node2: other.node,
+                        sources: { spreading: (act.activation + other.activation) / 2 },
+                    });
+                }
+            }
+        }
+        // Add pairs from link prediction
+        const linkSuggestions = await this.suggestEdges(15);
+        for (const suggestion of linkSuggestions) {
+            const key = suggestion.node1.id < suggestion.node2.id
+                ? `${suggestion.node1.id}:${suggestion.node2.id}`
+                : `${suggestion.node2.id}:${suggestion.node1.id}`;
+            if (candidates.has(key)) {
+                const candidate = candidates.get(key);
+                if (candidate) {
+                    candidate.sources.linkPrediction = suggestion.noveltyScore;
+                }
+            }
+            else {
+                candidates.set(key, {
+                    node1: suggestion.node1,
+                    node2: suggestion.node2,
+                    sources: { linkPrediction: suggestion.noveltyScore },
+                });
+            }
+        }
+        // Add pairs from semantic gaps
+        const stats = this.getEmbeddingStats();
+        if (stats.coverage > 0.5) {
+            const gaps = this.findSemanticGapsWithEmbeddings(15);
+            for (const gap of gaps) {
+                const key = gap.node1.id < gap.node2.id
+                    ? `${gap.node1.id}:${gap.node2.id}`
+                    : `${gap.node2.id}:${gap.node1.id}`;
+                if (candidates.has(key)) {
+                    const candidate = candidates.get(key);
+                    if (candidate) {
+                        candidate.sources.semanticGap = gap.embeddingSimilarity || 0;
+                    }
+                }
+                else {
+                    candidates.set(key, {
+                        node1: gap.node1,
+                        node2: gap.node2,
+                        sources: { semanticGap: gap.embeddingSimilarity || 0 },
+                    });
+                }
+            }
+        }
+        // Step 4: Score all candidates using information theory
+        const scored = [];
+        for (const [, candidate] of candidates) {
+            const infoGain = this.informationGain(candidate.node1.id, candidate.node2.id);
+            candidate.sources.informationGain = infoGain.combined;
+            // Compute final score - weight based on which sources found this pair
+            const sourceCount = Object.values(candidate.sources).filter((v) => v !== undefined).length;
+            let score = 0;
+            let reason = '';
+            if (candidate.sources.spreading) {
+                score += candidate.sources.spreading * 0.25;
+            }
+            if (candidate.sources.linkPrediction) {
+                score += candidate.sources.linkPrediction * 0.25;
+            }
+            if (candidate.sources.semanticGap) {
+                score += candidate.sources.semanticGap * 0.25;
+            }
+            score += infoGain.combined * 0.25;
+            // Bonus for being found by multiple algorithms
+            score *= 1 + (sourceCount - 1) * 0.2;
+            // Determine reason
+            if (sourceCount >= 3) {
+                reason = 'Multi-signal convergence';
+            }
+            else if (infoGain.clusterSurprisal > 0.5) {
+                reason = 'Cross-cluster bridge';
+            }
+            else if (candidate.sources.spreading &&
+                candidate.sources.spreading > 0.3) {
+                reason = 'Activation collision';
+            }
+            else if (candidate.sources.semanticGap &&
+                candidate.sources.semanticGap > 0.5) {
+                reason = 'Semantic similarity';
+            }
+            else {
+                reason = 'Structural affinity';
+            }
+            scored.push({
+                node1: candidate.node1,
+                node2: candidate.node2,
+                score: Math.round(score * 1000) / 1000,
+                reason,
+                sources: candidate.sources,
+            });
+        }
+        // Sort by score and return top results
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+    }
+    // ============================================================================
+    // Document Structure Methods
+    // ============================================================================
+    /**
+     * Get all document root nodes (nodes with isDocRoot = true)
+     */
+    getDocumentRoots() {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+        SELECT * FROM nodes WHERE active = 1 AND is_doc_root = 1
+        ORDER BY created_at DESC
+      `)
+            .all();
+        return rows.map((r) => this.rowToNode(r));
+    }
+    /**
+     * Get child nodes of a parent via "contains" edges
+     * Returns children in order based on their position in "next" chains within the parent
+     */
+    getChildren(parentId) {
+        const db = getDb();
+        // Get all nodes that this parent contains
+        const childRows = db
+            .prepare(`
+        SELECT n.* FROM nodes n
+        JOIN edges e ON n.id = e.to_id
+        WHERE e.from_id = ? AND e.type = 'contains' AND e.active = 1 AND n.active = 1
+      `)
+            .all(parentId);
+        const children = childRows.map((r) => this.rowToNode(r));
+        if (children.length <= 1)
+            return children;
+        // Order children by following "next" chains within the parent
+        // Find child that has no "next" pointing TO it (the first in sequence)
+        const _childIds = new Set(children.map((c) => c.id));
+        const nextTargets = new Set();
+        const nextEdges = db
+            .prepare(`
+        SELECT from_id, to_id FROM edges
+        WHERE type = 'next' AND active = 1
+        AND from_id IN (${children.map(() => '?').join(',')})
+        AND to_id IN (${children.map(() => '?').join(',')})
+      `)
+            .all(...children.map((c) => c.id), ...children.map((c) => c.id));
+        // Build next-pointer map and find targets
+        const nextMap = new Map();
+        for (const edge of nextEdges) {
+            nextMap.set(edge.from_id, edge.to_id);
+            nextTargets.add(edge.to_id);
+        }
+        // Find first child (not a target of any next edge)
+        let firstId = null;
+        for (const child of children) {
+            if (!nextTargets.has(child.id)) {
+                firstId = child.id;
+                break;
+            }
+        }
+        if (!firstId) {
+            // No clear first - just return unordered
+            return children;
+        }
+        // Follow the chain
+        const ordered = [];
+        const childMap = new Map(children.map((c) => [c.id, c]));
+        let currentId = firstId;
+        while (currentId && childMap.has(currentId)) {
+            const child = childMap.get(currentId);
+            if (child) {
+                ordered.push(child);
+                childMap.delete(currentId); // Prevent cycles
+            }
+            currentId = nextMap.get(currentId) || null;
+        }
+        // Add any remaining children that weren't in the chain
+        for (const remaining of childMap.values()) {
+            ordered.push(remaining);
+        }
+        return ordered;
+    }
+    /**
+     * Get the next-chain starting from a given node
+     * Follows "next" edges until no more are found
+     */
+    getNextChain(startId) {
+        const db = getDb();
+        const chain = [];
+        const startNode = this.getNode(startId);
+        if (!startNode)
+            return chain;
+        chain.push(startNode);
+        let currentId = startId;
+        const visited = new Set([currentId]);
+        while (true) {
+            const nextEdge = db
+                .prepare(`
+          SELECT to_id FROM edges
+          WHERE from_id = ? AND type = 'next' AND active = 1
+        `)
+                .get(currentId);
+            if (!nextEdge || visited.has(nextEdge.to_id))
+                break;
+            const nextNode = this.getNode(nextEdge.to_id);
+            if (!nextNode)
+                break;
+            chain.push(nextNode);
+            visited.add(nextEdge.to_id);
+            currentId = nextEdge.to_id;
+        }
+        return chain;
+    }
+    /**
+     * Get the full document tree starting from a root
+     * Returns a nested structure with children
+     */
+    getDocumentTree(rootId, maxDepth = 10) {
+        const node = this.getNode(rootId);
+        if (!node)
+            return null;
+        const buildTree = (nodeId, depth) => {
+            const n = this.getNode(nodeId);
+            if (!n || depth > maxDepth)
+                return null;
+            const children = this.getChildren(nodeId);
+            return {
+                node: n,
+                children: children
+                    .map((child) => buildTree(child.id, depth + 1))
+                    .filter((c) => c !== null),
+            };
+        };
+        return buildTree(rootId, 0);
+    }
+    /**
+     * Get concepts that a document node expresses (linked via "expresses" edges)
+     */
+    getExpressedConcepts(nodeId) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+        SELECT n.* FROM nodes n
+        JOIN edges e ON n.id = e.to_id
+        WHERE e.from_id = ? AND e.type = 'expresses' AND e.active = 1 AND n.active = 1
+      `)
+            .all(nodeId);
+        return rows.map((r) => this.rowToNode(r));
+    }
+    /**
+     * Get document nodes that express a given concept (reverse lookup)
+     */
+    getExpressingDocuments(conceptId) {
+        const db = getDb();
+        const rows = db
+            .prepare(`
+        SELECT n.* FROM nodes n
+        JOIN edges e ON n.id = e.from_id
+        WHERE e.to_id = ? AND e.type = 'expresses' AND e.active = 1 AND n.active = 1
+      `)
+            .all(conceptId);
+        return rows.map((r) => this.rowToNode(r));
+    }
+    /**
+     * Get the parent of a document node (via "contains" edge where this node is the target)
+     */
+    getParent(nodeId) {
+        const db = getDb();
+        const edge = db
+            .prepare(`
+        SELECT from_id FROM edges
+        WHERE to_id = ? AND type = 'contains' AND active = 1
+      `)
+            .get(nodeId);
+        if (!edge)
+            return null;
+        return this.getNode(edge.from_id);
+    }
+    /**
+     * Get the path from a document root to a specific node
+     * Returns array from root to node, or null if not found
+     */
+    getDocumentPath(nodeId) {
+        const path = [];
+        let currentId = nodeId;
+        const visited = new Set();
+        while (currentId && !visited.has(currentId)) {
+            const node = this.getNode(currentId);
+            if (!node)
+                return null;
+            path.unshift(node);
+            visited.add(currentId);
+            if (node.isDocRoot) {
+                return path;
+            }
+            const parent = this.getParent(currentId);
+            currentId = parent?.id || null;
+        }
+        return null; // No root found
+    }
+    /**
+     * Create a document node with proper structure
+     * Convenience method that sets up the node with document fields
+     */
+    createDocumentNode(input) {
+        // Validate document hierarchy requirement
+        if (!input.isDocRoot && !input.parentId) {
+            throw new Error('Document node must either be a root (isDocRoot: true) or have a parentId. ' +
+                'Orphan document nodes are not allowed.');
+        }
+        // If parentId provided, verify it exists
+        if (input.parentId) {
+            const parent = this.getNode(input.parentId);
+            if (!parent) {
+                throw new Error(`Parent node not found: ${input.parentId}`);
+            }
+        }
+        // Create the node
+        const node = this.createNode({
+            title: input.title,
+            trigger: input.trigger || 'foundation',
+            why: 'Document node',
+            understanding: input.summary || input.content.slice(0, 200),
+            content: input.content,
+            summary: input.summary,
+            level: input.level,
+            isDocRoot: input.isDocRoot,
+            fileType: input.fileType,
+            conversationId: input.conversationId,
+            toolCallId: input.toolCallId,
+        });
+        // Create contains edge if parent specified
+        if (input.parentId) {
+            const parent = this.getNode(input.parentId);
+            this.createEdge({
+                fromId: input.parentId,
+                toId: node.id,
+                type: 'contains',
+                explanation: `Contains ${input.level || 'content'}`,
+                why: `"${parent?.title || 'Parent'}" contains "${node.title}" as a ${input.level || 'child'} element in the document structure`,
+                conversationId: input.conversationId,
+                toolCallId: input.toolCallId,
+            });
+        }
+        // Create next edge if afterId specified
+        if (input.afterId) {
+            const prev = this.getNode(input.afterId);
+            this.createEdge({
+                fromId: input.afterId,
+                toId: node.id,
+                type: 'next',
+                explanation: 'Sequence',
+                why: `"${node.title}" follows "${prev?.title || 'Previous'}" in the reading order of the document`,
+                conversationId: input.conversationId,
+                toolCallId: input.toolCallId,
+            });
+        }
+        // Create expresses edges for linked concepts
+        if (input.expressesIds) {
+            for (const conceptId of input.expressesIds) {
+                const concept = this.getNode(conceptId);
+                this.createEdge({
+                    fromId: node.id,
+                    toId: conceptId,
+                    type: 'expresses',
+                    explanation: 'Expresses concept',
+                    why: `This document section discusses or elaborates on the concept "${concept?.title || conceptId}"`,
+                    conversationId: input.conversationId,
+                    toolCallId: input.toolCallId,
+                });
+            }
+        }
+        return node;
+    }
+    /**
+     * Flatten a document tree into a linear sequence for rendering
+     * Uses depth-first traversal, respecting next-chains at each level
+     */
+    flattenDocument(rootId) {
+        const result = [];
+        const visited = new Set();
+        const MAX_DEPTH = 50;
+        const traverse = (nodeId, depth) => {
+            // Prevent infinite recursion from cycles or excessive depth
+            if (visited.has(nodeId) || depth > MAX_DEPTH)
+                return;
+            visited.add(nodeId);
+            const node = this.getNode(nodeId);
+            if (!node)
+                return;
+            result.push({ node, depth });
+            // Get ordered children and traverse each
+            const children = this.getChildren(nodeId);
+            for (const child of children) {
+                traverse(child.id, depth + 1);
+            }
+        };
+        traverse(rootId, 0);
+        return result;
+    }
+    // ============================================================================
+    // Reference Resolution
+    // ============================================================================
+    /**
+     * Resolve soft references in text.
+     * Syntax: {{type:id_or_name}}
+     * Types: char, character, story, place, concept, node (generic)
+     *
+     * Examples:
+     *   {{char:n_abc123}} -> "Kael Thornwood"
+     *   {{char:Kael}} -> "Kael Thornwood" (by name)
+     *   {{concept:Authentication}} -> "Authentication"
+     *   {{node:n_xyz}} -> resolves any node by ID
+     */
+    resolveReferences(text) {
+        if (!text)
+            return text;
+        // Pattern: {{type:reference}}
+        const pattern = /\{\{(char|character|story|place|concept|node):([^}]+)\}\}/g;
+        return text.replace(pattern, (match, _type, ref) => {
+            const trimmedRef = ref.trim();
+            // Try to find the node
+            let node = null;
+            // First try by ID
+            if (trimmedRef.startsWith('n_')) {
+                node = this.getNode(trimmedRef);
+            }
+            // If not found by ID, try by name
+            if (!node) {
+                node = this.getNodeByName(trimmedRef);
+            }
+            // If still not found, return original placeholder
+            if (!node) {
+                console.warn(`Reference not found: ${match}`);
+                return match;
+            }
+            // Return the node's current name
+            return node.title;
+        });
+    }
+    /**
+     * Find a node by its title/name field
+     */
+    getNodeByName(name) {
+        for (const node of this.nodesCache.values()) {
+            if (node.active && node.title === name) {
+                return node;
+            }
+        }
+        return null;
+    }
+    /**
+     * Rename a node (update its title field)
+     * Returns the updated node or null if not found
+     */
+    renameNode(nodeId, newName) {
+        const db = getDb();
+        const node = this.getNode(nodeId);
+        if (!node) {
+            return null;
+        }
+        const now = new Date().toISOString();
+        const oldName = node.title;
+        db.prepare(`
+      UPDATE nodes
+      SET title = ?, updated_at = ?
+      WHERE id = ?
+    `).run(newName, now, nodeId);
+        // Update cache
+        node.title = newName;
+        node.updatedAt = now;
+        logEvent('revised', 'node', nodeId, null, `Renamed from "${oldName}" to "${newName}"`, {
+            oldName,
+            newName,
+        });
+        return node;
+    }
+}
+// Singleton instance
+let graphStoreInstance = null;
+export function getGraphStore() {
+    if (!graphStoreInstance) {
+        graphStoreInstance = new GraphStore();
+    }
+    return graphStoreInstance;
+}
+export function resetGraphStore() {
+    graphStoreInstance = null;
+}
+// ============================================================================
+// Cross-Project Access (Deprecated - Use sqlite.ts functions directly)
+// ============================================================================
+/**
+ * @deprecated Use sqlite.globalNodeLookup, sqlite.queryNodes, etc. instead.
+ * All databases are now loaded in memory at startup.
+ */
+export class ExternalGraphStore {
+    projectId;
+    constructor(_dbPath, projectId) {
+        console.warn('ExternalGraphStore is deprecated. Use sqlite.ts cross-project functions instead.');
+        this.projectId = projectId;
+    }
+    // Stub methods for backwards compatibility - these throw errors
+    getNode(_id) {
+        throw new Error('ExternalGraphStore is deprecated. Use sqlite.lookupExternalNode() instead.');
+    }
+    getAll() {
+        throw new Error('ExternalGraphStore is deprecated. Use sqlite.listExternalNodes() instead.');
+    }
+    close() {
+        // No-op - databases are managed by sqlite.ts
+    }
+}
+/**
+ * @deprecated Use sqlite.isProjectLoaded() and sqlite.* functions instead.
+ */
+export function getExternalGraphStore(_projectsDir, projectId) {
+    console.warn('getExternalGraphStore is deprecated. Use sqlite.* cross-project functions instead.');
+    return new ExternalGraphStore('', projectId);
+}
+//# sourceMappingURL=GraphStore.js.map