@soleri/core 2.11.0 → 7.0.0

package/src/vault/linking.ts

@@ -0,0 +1,333 @@
+/**
+ * LinkManager — Zettelkasten bidirectional linking for vault entries.
+ *
+ * Provides typed links between entries (supports, contradicts, extends, sequences),
+ * backlink traversal, graph walking, orphan detection, and link suggestions via FTS5.
+ *
+ * Ported from Salvador MCP with improvements:
+ * - Uses PersistenceProvider (not raw SQLite) for backend abstraction
+ * - Uses FTS5 for suggest_links (Salvador used TF-IDF cosine similarity)
+ * - Graceful degradation — all methods return empty on table-not-found
+ */
+
+import type { PersistenceProvider } from '../persistence/types.js';
+import type {
+  VaultLink,
+  VaultLinkRow,
+  LinkType,
+  LinkedEntry,
+  LinkSuggestion,
+} from './vault-types.js';
+
+export class LinkManager {
+  private initialized = false;
+
+  constructor(private provider: PersistenceProvider) {
+    this.ensureTable();
+  }
+
+  // ===========================================================================
+  // SCHEMA
+  // ===========================================================================
+
+  private ensureTable(): void {
+    if (this.initialized) return;
+    try {
+      this.provider.execSql(`
+        CREATE TABLE IF NOT EXISTS vault_links (
+          source_id TEXT NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+          target_id TEXT NOT NULL REFERENCES entries(id) ON DELETE CASCADE,
+          link_type TEXT NOT NULL CHECK(link_type IN ('supports', 'contradicts', 'extends', 'sequences')),
+          note TEXT,
+          created_at INTEGER NOT NULL,
+          PRIMARY KEY (source_id, target_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_links_target ON vault_links(target_id);
+        CREATE INDEX IF NOT EXISTS idx_links_type ON vault_links(link_type);
+      `);
+      this.initialized = true;
+    } catch {
+      // Table may already exist or DB may be read-only — degrade gracefully
+    }
+  }
+
+  // ===========================================================================
+  // CRUD
+  // ===========================================================================
+
+  /** Create a typed link between two entries. */
+  addLink(sourceId: string, targetId: string, linkType: LinkType, note?: string): void {
+    this.provider.run(
+      `INSERT OR REPLACE INTO vault_links (source_id, target_id, link_type, note, created_at)
+       VALUES (?, ?, ?, ?, ?)`,
+      [sourceId, targetId, linkType, note ?? null, Date.now()],
+    );
+  }
+
+  /** Remove a link between two entries. */
+  removeLink(sourceId: string, targetId: string): void {
+    this.provider.run('DELETE FROM vault_links WHERE source_id = ? AND target_id = ?', [
+      sourceId,
+      targetId,
+    ]);
+  }
+
+  /** Get all outgoing links FROM an entry. */
+  getLinks(entryId: string): VaultLink[] {
+    try {
+      const rows = this.provider.all<VaultLinkRow>(
+        'SELECT * FROM vault_links WHERE source_id = ?',
+        [entryId],
+      );
+      return rows.map(rowToVaultLink);
+    } catch {
+      return [];
+    }
+  }
+
+  /** Get all incoming links TO an entry (backlinks). */
+  getBacklinks(entryId: string): VaultLink[] {
+    try {
+      const rows = this.provider.all<VaultLinkRow>(
+        'SELECT * FROM vault_links WHERE target_id = ?',
+        [entryId],
+      );
+      return rows.map(rowToVaultLink);
+    } catch {
+      return [];
+    }
+  }
+
+  /** Get total link count (outgoing + incoming). */
+  getLinkCount(entryId: string): number {
+    try {
+      const row = this.provider.get<{ count: number }>(
+        'SELECT COUNT(*) as count FROM vault_links WHERE source_id = ? OR target_id = ?',
+        [entryId, entryId],
+      );
+      return row?.count ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  // ===========================================================================
+  // GRAPH TRAVERSAL
+  // ===========================================================================
+
+  /**
+   * Walk the link graph from a starting entry up to `depth` hops.
+   * Returns all connected entries with link metadata.
+   * BFS — walks both outgoing and incoming links (undirected).
+   */
+  traverse(entryId: string, depth: number = 2): LinkedEntry[] {
+    const visited = new Set<string>([entryId]);
+    const result: LinkedEntry[] = [];
+    let frontier = [entryId];
+
+    for (let d = 0; d < depth && frontier.length > 0; d++) {
+      const nextFrontier: string[] = [];
+
+      for (const currentId of frontier) {
+        // Outgoing
+        for (const link of this.getLinks(currentId)) {
+          if (!visited.has(link.targetId)) {
+            visited.add(link.targetId);
+            nextFrontier.push(link.targetId);
+            const entry = this.getEntryMeta(link.targetId);
+            if (entry) {
+              result.push({
+                ...entry,
+                linkType: link.linkType,
+                linkDirection: 'outgoing',
+                linkNote: link.note,
+              });
+            }
+          }
+        }
+        // Incoming
+        for (const link of this.getBacklinks(currentId)) {
+          if (!visited.has(link.sourceId)) {
+            visited.add(link.sourceId);
+            nextFrontier.push(link.sourceId);
+            const entry = this.getEntryMeta(link.sourceId);
+            if (entry) {
+              result.push({
+                ...entry,
+                linkType: link.linkType,
+                linkDirection: 'incoming',
+                linkNote: link.note,
+              });
+            }
+          }
+        }
+      }
+
+      frontier = nextFrontier;
+    }
+
+    return result;
+  }
+
+  // ===========================================================================
+  // ORPHAN DETECTION
+  // ===========================================================================
+
+  /** Find entries with zero links. */
+  getOrphans(
+    limit: number = 50,
+  ): Array<{ id: string; title: string; type: string; domain: string }> {
+    try {
+      return this.provider.all<{ id: string; title: string; type: string; domain: string }>(
+        `SELECT id, title, type, domain FROM entries
+         WHERE id NOT IN (SELECT source_id FROM vault_links)
+           AND id NOT IN (SELECT target_id FROM vault_links)
+         ORDER BY updated_at DESC LIMIT ?`,
+        [limit],
+      );
+    } catch {
+      return [];
+    }
+  }
+
+  // ===========================================================================
+  // LINK SUGGESTIONS (FTS5-powered — improvement over Salvador's TF-IDF)
+  // ===========================================================================
+
+  /** Find semantically similar entries as link candidates using FTS5. */
+  suggestLinks(entryId: string, limit: number = 5): LinkSuggestion[] {
+    try {
+      // Get the entry to build a search query
+      const entry = this.provider.get<{
+        title: string;
+        description: string;
+        type: string;
+        tags: string;
+      }>('SELECT title, description, type, tags FROM entries WHERE id = ?', [entryId]);
+      if (!entry) return [];
+
+      // Build FTS query from entry content — extract significant keywords only.
+      // FTS5 MATCH chokes on long raw text; use top keywords joined with OR.
+      const rawWords = `${entry.title} ${entry.description}`
+        .replace(/[^\w\s]/g, ' ')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 2);
+      // Deduplicate and take top 10 most significant words (skip common stop words)
+      const stopWords = new Set([
+        'the',
+        'and',
+        'for',
+        'with',
+        'from',
+        'this',
+        'that',
+        'are',
+        'was',
+        'not',
+        'but',
+        'have',
+        'has',
+        'use',
+        'can',
+        'will',
+        'all',
+        'each',
+        'than',
+        'its',
+        'more',
+        'when',
+        'into',
+        'also',
+        'any',
+        'may',
+        'only',
+        'should',
+        'which',
+      ]);
+      const unique = [...new Set(rawWords)].filter((w) => !stopWords.has(w));
+      const keywords = unique.slice(0, 10);
+      if (keywords.length === 0) return [];
+      const queryTerms = keywords.join(' OR ');
+
+      // FTS5 match with BM25 ranking
+      const matches = this.provider.all<{
+        id: string;
+        title: string;
+        type: string;
+        domain: string;
+        rank: number;
+      }>(
+        `SELECT e.id, e.title, e.type, e.domain, rank
+         FROM entries_fts fts
+         JOIN entries e ON e.rowid = fts.rowid
+         WHERE entries_fts MATCH ?
+         ORDER BY rank
+         LIMIT ?`,
+        [queryTerms, limit + 5],
+      );
+
+      // Filter out self and already-linked entries
+      const existingLinks = new Set([
+        ...this.getLinks(entryId).map((l) => l.targetId),
+        ...this.getBacklinks(entryId).map((l) => l.sourceId),
+      ]);
+
+      return matches
+        .filter((m) => m.id !== entryId && !existingLinks.has(m.id))
+        .slice(0, limit)
+        .map((m) => {
+          const suggestedType = inferLinkType(entry.type, m.type);
+          return {
+            entryId: m.id,
+            title: m.title,
+            type: m.type,
+            score: Math.abs(m.rank), // FTS5 rank is negative (lower = better)
+            suggestedType,
+            reason: `${m.type} in ${m.domain}`,
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  // ===========================================================================
+  // PRIVATE
+  // ===========================================================================
+
+  private getEntryMeta(
+    entryId: string,
+  ): Omit<LinkedEntry, 'linkType' | 'linkDirection' | 'linkNote'> | null {
+    try {
+      const row = this.provider.get<{ id: string; title: string; type: string; domain: string }>(
+        'SELECT id, title, type, domain FROM entries WHERE id = ?',
+        [entryId],
+      );
+      return row ?? null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function rowToVaultLink(row: VaultLinkRow): VaultLink {
+  return {
+    sourceId: row.source_id,
+    targetId: row.target_id,
+    linkType: row.link_type as LinkType,
+    note: row.note ?? undefined,
+    createdAt: row.created_at,
+  };
+}
+
+function inferLinkType(sourceType: string, targetType: string): LinkType {
+  if (sourceType === 'pattern' && targetType === 'anti-pattern') return 'contradicts';
+  if (sourceType === 'anti-pattern' && targetType === 'pattern') return 'contradicts';
+  if (targetType === 'rule') return 'supports';
+  return 'extends';
+}

package/src/vault/vault-types.ts

@@ -48,3 +48,49 @@ export interface VaultTierInfo {
   connected: boolean;
   entryCount: number;
 }
+
+// =============================================================================
+// ZETTELKASTEN LINKS
+// =============================================================================
+
+/** Typed relationship between two vault entries. */
+export type LinkType = 'supports' | 'contradicts' | 'extends' | 'sequences';
+
+/** A directional, typed link between two vault entries. */
+export interface VaultLink {
+  sourceId: string;
+  targetId: string;
+  linkType: LinkType;
+  note?: string;
+  createdAt: number;
+}
+
+/** Raw SQLite row from vault_links table. */
+export interface VaultLinkRow {
+  source_id: string;
+  target_id: string;
+  link_type: string;
+  note: string | null;
+  created_at: number;
+}
+
+/** Entry enriched with link context for graph traversal results. */
+export interface LinkedEntry {
+  id: string;
+  title: string;
+  type: string;
+  domain: string;
+  linkType: LinkType;
+  linkDirection: 'outgoing' | 'incoming';
+  linkNote?: string;
+}
+
+/** Suggested link candidate from semantic/FTS similarity. */
+export interface LinkSuggestion {
+  entryId: string;
+  title: string;
+  type: string;
+  score: number;
+  suggestedType: LinkType;
+  reason: string;
+}

package/src/vault/vault.ts

@@ -178,6 +178,7 @@ export class Vault {
     `);
     this.migrateBrainSchema();
     this.migrateTemporalSchema();
+    this.migrateOriginColumn();
     this.migrateContentHash();
     this.migrateTierColumn();
   }
@@ -206,6 +207,17 @@ export class Vault {
     }
   }
 
+  private migrateOriginColumn(): void {
+    try {
+      this.provider.run(
+        "ALTER TABLE entries ADD COLUMN origin TEXT NOT NULL DEFAULT 'user' CHECK(origin IN ('agent', 'pack', 'user'))",
+      );
+    } catch {
+      // Column already exists
+    }
+    this.provider.execSql('CREATE INDEX IF NOT EXISTS idx_entries_origin ON entries(origin)');
+  }
+
   private migrateContentHash(): void {
     try {
       this.provider.run('ALTER TABLE entries ADD COLUMN content_hash TEXT');
@@ -293,12 +305,12 @@ export class Vault {
 
   seed(entries: IntelligenceEntry[]): number {
     const sql = `
-      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until,content_hash,tier)
-      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash,@tier)
+      INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until,content_hash,tier,origin)
+      VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash,@tier,@origin)
       ON CONFLICT(id) DO UPDATE SET type=excluded.type,domain=excluded.domain,title=excluded.title,severity=excluded.severity,
         description=excluded.description,context=excluded.context,example=excluded.example,counter_example=excluded.counter_example,
         why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,valid_from=excluded.valid_from,valid_until=excluded.valid_until,
-        content_hash=excluded.content_hash,tier=excluded.tier,updated_at=unixepoch()
+        content_hash=excluded.content_hash,tier=excluded.tier,origin=excluded.origin,updated_at=unixepoch()
     `;
     return this.provider.transaction(() => {
       let count = 0;
@@ -320,6 +332,7 @@ export class Vault {
           validUntil: entry.validUntil ?? null,
           contentHash: computeContentHash(entry),
           tier: entry.tier ?? 'agent',
+          origin: entry.origin ?? 'agent',
         });
         count++;
         if (this.syncManager) {
@@ -330,6 +343,24 @@ export class Vault {
     });
   }
 
+  /**
+   * Install a knowledge pack — seeds entries with origin:'pack' and content-hash dedup.
+   * Packs are installable domain knowledge (UX laws, design tokens, clean code rules).
+   * Unlike seed(), this forces origin:'pack' regardless of what the entry says.
+   */
+  installPack(entries: IntelligenceEntry[]): { installed: number; skipped: number } {
+    let installed = 0;
+    let skipped = 0;
+    // Tag all entries with origin:'pack' and seed — seed() handles its own transaction
+    const tagged = entries.map((e) => ({ ...e, origin: 'pack' as const }));
+    const results = this.seedDedup(tagged);
+    for (const r of results) {
+      if (r.action === 'inserted') installed++;
+      else skipped++;
+    }
+    return { installed, skipped };
+  }
+
   /**
    * Seed entries with content-hash dedup. Returns per-entry results.
    * Unlike seed(), skips entries whose content already exists in the vault.
@@ -360,6 +391,7 @@ export class Vault {
       domain?: string;
       type?: string;
       severity?: string;
+      origin?: 'agent' | 'pack' | 'user';
       limit?: number;
       includeExpired?: boolean;
     },
@@ -379,6 +411,10 @@ export class Vault {
       filters.push('e.severity = @severity');
       fp.severity = options.severity;
     }
+    if (options?.origin) {
+      filters.push('e.origin = @origin');
+      fp.origin = options.origin;
+    }
     if (!options?.includeExpired) {
       const now = Math.floor(Date.now() / 1000);
       filters.push('(e.valid_until IS NULL OR e.valid_until > @now)');
@@ -386,14 +422,30 @@ export class Vault {
       fp.now = now;
     }
     const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
+
+    // Build FTS5 query: use OR between terms for broader matching,
+    // with title column boosted 3x for relevance ranking.
+    // FTS5 BM25 with default AND degrades with more entries because
+    // fewer documents match ALL terms simultaneously.
+    const ftsQuery = buildFtsQuery(query);
+
     try {
       const rows = this.provider.all<Record<string, unknown>>(
-        `SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`,
-        { query, limit, ...fp },
+        `SELECT e.*, bm25(entries_fts, 5.0, 10.0, 3.0, 1.0, 2.0) as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score ASC LIMIT @limit`,
+        { query: ftsQuery, limit, ...fp },
       );
       return rows.map(rowToSearchResult);
     } catch {
-      return [];
+      // Fallback: try original query if FTS5 syntax fails
+      try {
+        const rows = this.provider.all<Record<string, unknown>>(
+          `SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`,
+          { query, limit, ...fp },
+        );
+        return rows.map(rowToSearchResult);
+      } catch {
+        return [];
+      }
     }
   }
 
@@ -408,6 +460,7 @@ export class Vault {
     domain?: string;
     type?: string;
     severity?: string;
+    origin?: 'agent' | 'pack' | 'user';
     tags?: string[];
     limit?: number;
     offset?: number;
@@ -427,6 +480,10 @@ export class Vault {
       filters.push('severity = @severity');
       params.severity = options.severity;
     }
+    if (options?.origin) {
+      filters.push('origin = @origin');
+      params.origin = options.origin;
+    }
     if (options?.tags?.length) {
       const c = options.tags.map((t, i) => {
         params[`tag${i}`] = `%"${t}"%`;
@@ -1133,13 +1190,43 @@ function rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
     tags: JSON.parse((row.tags as string) || '[]'),
     appliesTo: JSON.parse((row.applies_to as string) || '[]'),
     tier: (row.tier as IntelligenceEntry['tier']) ?? undefined,
+    origin: (row.origin as IntelligenceEntry['origin']) ?? undefined,
     validFrom: (row.valid_from as number) ?? undefined,
     validUntil: (row.valid_until as number) ?? undefined,
   };
 }
 
 function rowToSearchResult(row: Record<string, unknown>): SearchResult {
-  return { entry: rowToEntry(row), score: row.score as number };
+  // bm25() returns negative scores (lower = better), normalize to positive
+  const rawScore = row.score as number;
+  const score = rawScore < 0 ? -rawScore : rawScore;
+  return { entry: rowToEntry(row), score };
+}
+
+/**
+ * Build an FTS5 query from natural language input.
+ *
+ * Converts "React render performance memo" to:
+ *   {title}: (react OR render OR performance OR memo) OR (react OR render OR performance OR memo)
+ *
+ * Uses OR matching (not AND) so results include partial matches.
+ * FTS5 BM25 ranks documents with more matching terms higher.
+ * Title column is boosted via bm25() weights in the SQL query.
+ */
+function buildFtsQuery(query: string): string {
+  const terms = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((t) => t.length >= 2)
+    .map((t) => t.replace(/[^a-z0-9]/g, ''))
+    .filter(Boolean);
+
+  if (terms.length === 0) return query;
+  if (terms.length === 1) return terms[0];
+
+  // Use OR to match any term — BM25 ranks by how many terms match
+  const orTerms = terms.join(' OR ');
+  return orTerms;
 }
 
 function rowToMemory(row: Record<string, unknown>): Memory {