@monoes/monograph 1.1.0 → 1.2.0

package/src/staleness/git-staleness.ts

@@ -0,0 +1,63 @@
+import { execSync } from 'child_process';
+import type { MonographDb } from '../storage/db.js';
+
+export interface StalenessReport {
+  isStale: boolean;
+  indexedAt: string | null;
+  indexedCommit: string | null;
+  currentCommit: string | null;
+  changedSince: string[];
+  staleSince: string | null;
+}
+
+export function checkStaleness(db: MonographDb, repoPath: string): StalenessReport {
+  // 1. Get stored commit hash
+  const row = db.prepare("SELECT value FROM index_meta WHERE key = 'last_commit_hash'").get() as { value: string } | undefined;
+  const indexedCommitFull = row?.value ?? null;
+
+  // 2. Get current HEAD (full SHA — --short output length varies by repo size)
+  let currentCommit: string | null = null;
+  try {
+    currentCommit = execSync('git rev-parse HEAD', { cwd: repoPath, encoding: 'utf8' }).trim();
+  } catch {
+    // Not a git repo or git not available
+    return { isStale: false, indexedAt: null, indexedCommit: null, currentCommit: null, changedSince: [], staleSince: null };
+  }
+
+  // Display short SHA (7 chars) for the interface field; compare full SHAs for correctness
+  const indexedCommitShort = indexedCommitFull ? indexedCommitFull.slice(0, 7) : null;
+  const currentCommitShort = currentCommit ? currentCommit.slice(0, 7) : null;
+
+  // 3. If no stored commit or full SHAs match, not stale
+  if (!indexedCommitFull || indexedCommitFull === currentCommit) {
+    return { isStale: false, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
+  }
+
+  // Guard: indexedCommitFull is read from SQLite — validate before shell interpolation
+  if (!/^[0-9a-f]{7,40}$/i.test(indexedCommitFull)) {
+    return { isStale: true, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince: [], staleSince: null };
+  }
+
+  // 4. Get changed files between indexed commit and HEAD
+  let changedSince: string[] = [];
+  try {
+    const diff = execSync(`git diff --name-only ${indexedCommitFull}..HEAD`, { cwd: repoPath, encoding: 'utf8' });
+    changedSince = diff.trim().split('\n').filter(Boolean);
+  } catch {
+    changedSince = [];
+  }
+
+  // 5. Get staleSince timestamp (first diverging commit after indexed commit)
+  let staleSince: string | null = null;
+  try {
+    const firstCommit = execSync(
+      `git log --format="%ai" ${indexedCommitFull}..HEAD --reverse --max-count=1`,
+      { cwd: repoPath, encoding: 'utf8' }
+    ).trim();
+    staleSince = firstCommit || null;
+  } catch {
+    staleSince = null;
+  }
+
+  return { isStale: true, indexedAt: null, indexedCommit: indexedCommitShort, currentCommit: currentCommitShort, changedSince, staleSince };
+}

package/src/storage/db.ts

@@ -4,6 +4,7 @@ import { dirname } from 'path';
 import {
   CREATE_NODES, CREATE_EDGES, CREATE_COMMUNITIES,
   CREATE_INDEX_META, CREATE_NODES_FTS, CREATE_INDEXES, FTS_SYNC_TRIGGERS,
+  CREATE_EMBEDDINGS, CREATE_WIKI_PAGES,
 } from './schema.js';
 import { MonographError } from '../types.js';
 
@@ -34,6 +35,8 @@ function applyMigrations(db: MonographDb): void {
   db.exec(CREATE_NODES_FTS);
   for (const idx of CREATE_INDEXES) db.exec(idx);
   db.exec(FTS_SYNC_TRIGGERS);
+  db.exec(CREATE_EMBEDDINGS);
+  db.exec(CREATE_WIKI_PAGES);
 }
 
 /** Write to a .tmp file then rename for atomic replacement. */

package/src/storage/edge-store.ts

@@ -1,10 +1,10 @@
 import type Database from 'better-sqlite3';
-import type { MonographEdge } from '../types.js';
+import type { EvidenceEntry, MonographEdge } from '../types.js';
 
 export function insertEdge(db: Database.Database, edge: MonographEdge): void {
   db.prepare(`
-    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score)
-    VALUES (?, ?, ?, ?, ?, ?)
+    INSERT OR REPLACE INTO edges (id, source_id, target_id, relation, confidence, confidence_score, reason, evidence)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     edge.id,
     edge.sourceId,
@@ -12,6 +12,8 @@ export function insertEdge(db: Database.Database, edge: MonographEdge): void {
     edge.relation,
     edge.confidence,
     edge.confidenceScore,
+    edge.reason ?? null,
+    edge.evidence != null ? JSON.stringify(edge.evidence) : null,
   );
 }
 
@@ -57,5 +59,7 @@ function rowToEdge(row: Record<string, unknown>): MonographEdge {
     relation: row.relation as MonographEdge['relation'],
     confidence: row.confidence as MonographEdge['confidence'],
     confidenceScore: row.confidence_score as number,
+    reason: row.reason as string | undefined,
+    evidence: row.evidence ? JSON.parse(row.evidence as string) as EvidenceEntry[] : undefined,
   };
 }

package/src/storage/embedding-store.ts

@@ -0,0 +1,76 @@
+import type Database from 'better-sqlite3';
+
+/**
+ * CRUD operations for the embeddings table.
+ *
+ * Vectors are stored as BLOBs (raw Float32Array bytes) and reconstructed on read.
+ */
+
+export function upsertEmbedding(
+  db: Database.Database,
+  nodeId: string,
+  vector: Float32Array,
+  contentHash?: string,
+): void {
+  // Migrate existing DBs that may not have the content_hash column yet.
+  try {
+    db.exec('ALTER TABLE embeddings ADD COLUMN content_hash TEXT');
+  } catch {
+    // Column already exists — ignore.
+  }
+  const buf = Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength);
+  db
+    .prepare(
+      'INSERT OR REPLACE INTO embeddings (node_id, vector, content_hash) VALUES (?, ?, ?)',
+    )
+    .run(nodeId, buf, contentHash ?? null);
+}
+
+export function getEmbeddingContentHash(db: Database.Database, nodeId: string): string | null {
+  const row = db
+    .prepare('SELECT content_hash FROM embeddings WHERE node_id = ?')
+    .get(nodeId) as { content_hash: string | null } | undefined;
+  return row?.content_hash ?? null;
+}
+
+export function isEmbeddingStale(
+  db: Database.Database,
+  nodeId: string,
+  currentHash: string,
+): boolean {
+  const stored = getEmbeddingContentHash(db, nodeId);
+  return stored !== currentHash;
+}
+
+export function getEmbedding(db: Database.Database, nodeId: string): Float32Array | null {
+  const row = db.prepare('SELECT vector FROM embeddings WHERE node_id = ?').get(nodeId) as
+    | { vector: Buffer }
+    | undefined;
+  if (!row) return null;
+  return bufToFloat32(row.vector);
+}
+
+export function getAllEmbeddings(db: Database.Database): Map<string, Float32Array> {
+  const rows = db.prepare('SELECT node_id, vector FROM embeddings').all() as {
+    node_id: string;
+    vector: Buffer;
+  }[];
+  const result = new Map<string, Float32Array>();
+  for (const row of rows) {
+    result.set(row.node_id, bufToFloat32(row.vector));
+  }
+  return result;
+}
+
+export function countEmbeddings(db: Database.Database): number {
+  const row = db.prepare('SELECT COUNT(*) AS n FROM embeddings').get() as { n: number };
+  return row.n;
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function bufToFloat32(buf: Buffer): Float32Array {
+  // Copy to a fresh ArrayBuffer so slice offset doesn't cause issues
+  const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  return new Float32Array(ab);
+}

package/src/storage/file-cache.ts

@@ -0,0 +1,64 @@
+import { createHash } from 'crypto';
+import type { MonographDb } from './db.js';
+
+export interface FileCacheEntry {
+  filePath: string;
+  contentHash: string;   // SHA-256 hex of file content (using node:crypto — xxh3 proxy)
+  lastParsed: number;    // unix timestamp ms
+  nodeCount: number;     // how many nodes were created from this file
+  edgeCount: number;
+}
+
+export function hashFileContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+export function isFileCached(db: MonographDb, filePath: string, contentHash: string): boolean {
+  const row = db.prepare(
+    'SELECT content_hash FROM file_cache WHERE file_path = ?'
+  ).get(filePath) as { content_hash: string } | undefined;
+  return row?.content_hash === contentHash;
+}
+
+export function updateFileCache(db: MonographDb, entry: FileCacheEntry): void {
+  db.prepare(`
+    INSERT OR REPLACE INTO file_cache (file_path, content_hash, last_parsed, node_count, edge_count)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(entry.filePath, entry.contentHash, entry.lastParsed, entry.nodeCount, entry.edgeCount);
+}
+
+export function getFileCacheStats(db: MonographDb): {
+  totalCached: number;
+  hitRate: number;
+  stalePaths: string[];
+} {
+  const totalCached = (db.prepare('SELECT COUNT(*) as c FROM file_cache').get() as { c: number }).c;
+
+  const totalNodes = (db.prepare(
+    "SELECT COUNT(DISTINCT file_path) as c FROM nodes WHERE file_path IS NOT NULL"
+  ).get() as { c: number }).c;
+
+  const hitRate = totalNodes > 0 ? totalCached / totalNodes : 0;
+
+  // Find stale paths: cached entries whose file no longer exists in nodes table
+  const cachedPaths = db.prepare('SELECT file_path, content_hash FROM file_cache').all() as {
+    file_path: string;
+    content_hash: string;
+  }[];
+
+  const indexedPaths = new Set<string>(
+    (db.prepare("SELECT DISTINCT file_path FROM nodes WHERE file_path IS NOT NULL").all() as {
+      file_path: string;
+    }[]).map(r => r.file_path)
+  );
+
+  const stalePaths = cachedPaths
+    .filter(r => !indexedPaths.has(r.file_path))
+    .map(r => r.file_path);
+
+  return { totalCached, hitRate, stalePaths };
+}
+
+export function clearFileCache(db: MonographDb): void {
+  db.prepare('DELETE FROM file_cache').run();
+}

package/src/storage/fts-store.ts

@@ -15,33 +15,74 @@ export function ftsSearch(
   limit: number,
   label?: string,
 ): FtsResult[] {
-  // Clean and sanitize the query for FTS5
-  const safeQuery = query.replace(/['"*]/g, ' ').trim();
+  // Sanitize: strip only characters that break FTS5 MATCH syntax (* still stripped,
+  // trigram handles substring natively; " is now preserved since trigram doesn't need it removed)
+  const safeQuery = query.replace(/[*]/g, ' ').trim();
   if (!safeQuery) return [];
 
-  // Add wildcard for prefix matching
-  const ftsPrefixQuery = safeQuery.split(/\s+/).map((term) => term + '*').join(' ');
+  // Trigram handles substring matching natively — no need to append * to each term
+  const ftsQuery = safeQuery.split(/\s+/).join(' ');
 
-  let sql = `
+  let matchSql = `
     SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
            nodes_fts.rank
     FROM nodes_fts
     JOIN nodes n ON n.rowid = nodes_fts.rowid
     WHERE nodes_fts MATCH ?
   `;
-  const params: unknown[] = [ftsPrefixQuery];
+  const matchParams: unknown[] = [ftsQuery];
   if (label) {
-    sql += ' AND n.label = ?';
-    params.push(label);
+    matchSql += ' AND n.label = ?';
+    matchParams.push(label);
   }
-  sql += ' ORDER BY nodes_fts.rank LIMIT ?';
-  params.push(limit);
-
-  const rows = db.prepare(sql).all(...(params as [string, ...unknown[]])) as Record<
-    string,
-    unknown
-  >[];
-  return rows.map((r) => ({
+  matchSql += ' ORDER BY nodes_fts.rank LIMIT ?';
+  matchParams.push(limit);
+
+  let matchRows: Record<string, unknown>[] = [];
+  try {
+    matchRows = db.prepare(matchSql).all(...(matchParams as [string, ...unknown[]])) as Record<
+      string,
+      unknown
+    >[];
+  } catch {
+    // FTS MATCH can throw on malformed queries; fall through to LIKE path
+  }
+
+  // For short queries (≤2 chars) trigram requires at least 3 characters to fire, so
+  // supplement with a LIKE fallback to catch single/double-character matches.
+  if (safeQuery.length <= 2) {
+    const escapedQuery = safeQuery.replace(/%/g, '\\%').replace(/_/g, '\\_');
+    const likePattern = `%${escapedQuery}%`;
+    let likeSql = `
+      SELECT n.id, n.name, n.norm_label, n.file_path, n.label,
+             0 AS rank
+      FROM nodes n
+      WHERE (n.name LIKE ? OR n.norm_label LIKE ? OR n.file_path LIKE ?)
+    `;
+    const likeParams: unknown[] = [likePattern, likePattern, likePattern];
+    if (label) {
+      likeSql += ' AND n.label = ?';
+      likeParams.push(label);
+    }
+    likeSql += ' LIMIT ?';
+    likeParams.push(limit);
+
+    const likeRows = db.prepare(likeSql).all(...(likeParams as [string, ...unknown[]])) as Record<
+      string,
+      unknown
+    >[];
+
+    // Merge: MATCH results first, append LIKE results not already present
+    const seenIds = new Set(matchRows.map((r) => r.id as string));
+    for (const r of likeRows) {
+      if (!seenIds.has(r.id as string)) {
+        matchRows.push(r);
+        seenIds.add(r.id as string);
+      }
+    }
+  }
+
+  return matchRows.slice(0, limit).map((r) => ({
     id: r.id as string,
     name: r.name as string,
     normLabel: r.norm_label as string,
@@ -50,3 +91,134 @@ export function ftsSearch(
     rank: r.rank as number,
   }));
 }
+
+// ── Hybrid search ─────────────────────────────────────────────────────────────
+
+export interface HybridSearchResult extends FtsResult {
+  combinedScore: number;
+  matchStrategy: 'fts' | 'like' | 'fuzzy';
+}
+
+/**
+ * Computes an in-memory fuzzy sequence score for `query` against `name`.
+ * Walks through query chars left-to-right, finding each in `name` sequentially.
+ * Returns a score in [0, 1]: higher means a tighter match.
+ */
+function computeFuzzyScore(name: string, query: string): number {
+  if (!query.length) return 0;
+  const lname = name.toLowerCase();
+  const lquery = query.toLowerCase();
+  let nameIdx = 0;
+  let matched = 0;
+  let gapPenalty = 0;
+  let lastMatchPos = -1;
+
+  for (let qi = 0; qi < lquery.length; qi++) {
+    const ch = lquery[qi];
+    const pos = lname.indexOf(ch, nameIdx);
+    if (pos === -1) break;
+    matched++;
+    if (lastMatchPos !== -1) {
+      gapPenalty += pos - lastMatchPos - 1;
+    }
+    lastMatchPos = pos;
+    nameIdx = pos + 1;
+  }
+
+  if (matched === 0) return 0;
+  const matchRatio = matched / lquery.length;
+  const normalizedGap = gapPenalty / (lname.length || 1);
+  return matchRatio * (1 / (1 + normalizedGap));
+}
+
+/** Returns a small bonus based on node label to favour structural node types. */
+function computeNodeTypeBonus(label: string): number {
+  if (label === 'File' || label === 'Module') return 0.02;
+  if (label === 'Class') return 0.01;
+  return 0;
+}
+
+/**
+ * Hybrid search combining three strategies:
+ *  1. FTS5 (trigram) BM25 match via `ftsSearch`
+ *  2. LIKE fallback for short queries (≤3 chars) or when FTS returns 0 results
+ *  3. In-memory fuzzy character-sequence scoring applied to all candidates
+ *
+ * Results are deduped by id (highest combinedScore wins), re-ranked, and
+ * trimmed to `limit`. The existing `ftsSearch` is left unchanged.
+ */
+export function hybridSearch(
+  db: Database.Database,
+  query: string,
+  limit: number,
+  label?: string,
+): HybridSearchResult[] {
+  const safeQuery = query.replace(/[*]/g, ' ').trim();
+  if (!safeQuery) return [];
+
+  // id → best result so far
+  const best = new Map<string, HybridSearchResult>();
+
+  const upsert = (result: HybridSearchResult): void => {
+    const existing = best.get(result.id);
+    if (!existing || result.combinedScore > existing.combinedScore) {
+      best.set(result.id, result);
+    }
+  };
+
+  // ── Strategy 1: FTS5 BM25 ──────────────────────────────────────────────────
+  const ftsRows = ftsSearch(db, safeQuery, limit * 2, label);
+  for (const row of ftsRows) {
+    // FTS5 rank is negative; larger magnitude = better match. Map to (0,1) with higher = better.
+    const absRank = Math.abs(row.rank);
+    const ftsScore = absRank / (1 + absRank);
+    const fuzz = computeFuzzyScore(row.name, safeQuery);
+    const combined = ftsScore + fuzz + computeNodeTypeBonus(row.label);
+    upsert({ ...row, combinedScore: combined, matchStrategy: 'fts' });
+  }
+
+  // ── Strategy 2: LIKE fallback ──────────────────────────────────────────────
+  // Always run for short queries (≤3 chars) or when FTS returned nothing.
+  if (safeQuery.length <= 3 || ftsRows.length === 0) {
+    const escapedSafeQuery = safeQuery.replace(/%/g, '\\%').replace(/_/g, '\\_');
+    const likePattern = `%${escapedSafeQuery}%`;
+    let likeSql = `
+      SELECT n.id, n.name, n.norm_label, n.file_path, n.label
+      FROM nodes n
+      WHERE (n.name LIKE ? OR n.norm_label LIKE ?)
+    `;
+    const likeParams: unknown[] = [likePattern, likePattern];
+    if (label) {
+      likeSql += ' AND n.label = ?';
+      likeParams.push(label);
+    }
+    likeSql += ' LIMIT ?';
+    likeParams.push(limit * 2);
+
+    const likeRows = db
+      .prepare(likeSql)
+      .all(...(likeParams as [string, ...unknown[]])) as Record<string, unknown>[];
+
+    for (const r of likeRows) {
+      const name = r.name as string;
+      const lbl = r.label as string;
+      const fuzz = computeFuzzyScore(name, safeQuery);
+      const combined = 0.3 + fuzz + computeNodeTypeBonus(lbl);
+      upsert({
+        id: r.id as string,
+        name,
+        normLabel: r.norm_label as string,
+        filePath: (r.file_path as string | null) ?? null,
+        label: lbl,
+        rank: 0,
+        combinedScore: combined,
+        matchStrategy: 'like',
+      });
+    }
+  }
+
+  // ── Sort, dedupe (handled by Map), slice ───────────────────────────────────
+  return Array.from(best.values())
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, limit);
+}

package/src/storage/node-store.ts

@@ -1,6 +1,6 @@
 import type Database from 'better-sqlite3';
 import type { MonographNode } from '../types.js';
-import { toNormLabel } from '../types.js';
+import { toNormLabel, MonographError } from '../types.js';
 
 export function insertNode(db: Database.Database, node: MonographNode): void {
   db.prepare(`
@@ -55,6 +55,105 @@ export function countNodes(db: Database.Database): number {
   return row.n;
 }
 
+// ── Property registry ─────────────────────────────────────────────────────────
+
+export interface PropertyDef {
+  ident: string;
+  type: string;
+  cardinality: string;
+  viewContext: string;
+  closedValues: string[] | null;
+  description: string | null;
+  queryable: boolean;
+}
+
+function rowToPropDef(row: Record<string, unknown>): PropertyDef {
+  return {
+    ident: row.ident as string,
+    type: row.type as string,
+    cardinality: row.cardinality as string,
+    viewContext: row.view_context as string,
+    closedValues: row.closed_values ? JSON.parse(row.closed_values as string) : null,
+    description: (row.description as string | null) ?? null,
+    queryable: (row.queryable as number) === 1,
+  };
+}
+
+/** List all registered property definitions */
+export function listProperties(db: Database.Database): PropertyDef[] {
+  const rows = db.prepare('SELECT * FROM node_properties ORDER BY ident').all() as Record<string, unknown>[];
+  return rows.map(rowToPropDef);
+}
+
+/** Get a single property definition */
+export function getProperty(db: Database.Database, ident: string): PropertyDef | null {
+  const row = db.prepare('SELECT * FROM node_properties WHERE ident = ?').get(ident) as Record<string, unknown> | undefined;
+  return row ? rowToPropDef(row) : null;
+}
+
+/** Register or update a custom property */
+export function upsertProperty(db: Database.Database, def: PropertyDef): void {
+  db.prepare(`
+    INSERT INTO node_properties (ident, type, cardinality, view_context, closed_values, description, queryable)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(ident) DO UPDATE SET
+      type = excluded.type,
+      cardinality = excluded.cardinality,
+      view_context = excluded.view_context,
+      closed_values = excluded.closed_values,
+      description = excluded.description,
+      queryable = excluded.queryable
+  `).run(
+    def.ident,
+    def.type,
+    def.cardinality,
+    def.viewContext,
+    def.closedValues != null ? JSON.stringify(def.closedValues) : null,
+    def.description ?? null,
+    def.queryable ? 1 : 0,
+  );
+}
+
+/**
+ * Query nodes by a typed property value extracted from their JSON properties column.
+ * For queryable properties only.
+ * @param ident - property ident (e.g. 'layer', 'tags', 'ua_type')
+ * @param value - value to match (exact for closed/text, numeric comparison for number)
+ * @param comparator - '=' | 'LIKE' | '>' | '<' (default '=')
+ */
+export function queryByProperty(
+  db: Database.Database,
+  ident: string,
+  value: string | number | boolean,
+  comparator: '=' | 'LIKE' | '>' | '<' = '=',
+  limit = 100,
+): Array<{ id: string; name: string; label: string; filePath: string | null; propertyValue: unknown }> {
+  const propDef = getProperty(db, ident);
+  if (!propDef) {
+    throw new MonographError(`Unknown property: '${ident}'. Register it first with upsertProperty.`);
+  }
+  if (!propDef.queryable) {
+    throw new MonographError(`Property '${ident}' is not queryable (view_context may be 'never' or queryable=false).`);
+  }
+
+  const extractExpr = `json_extract(properties, '$.${ident}')`;
+  const rows = db.prepare(`
+    SELECT id, name, label, file_path, ${extractExpr} AS property_value
+    FROM nodes
+    WHERE properties IS NOT NULL
+      AND ${extractExpr} ${comparator} ?
+    LIMIT ?
+  `).all(value, limit) as Array<Record<string, unknown>>;
+
+  return rows.map(r => ({
+    id: r.id as string,
+    name: r.name as string,
+    label: r.label as string,
+    filePath: (r.file_path as string | null) ?? null,
+    propertyValue: r.property_value,
+  }));
+}
+
 function rowToNode(row: Record<string, unknown>): MonographNode {
   return {
     id: row.id as string,

package/src/storage/schema.ts

@@ -10,7 +10,8 @@ CREATE TABLE IF NOT EXISTS nodes (
   community_id INTEGER,
   is_exported INTEGER NOT NULL DEFAULT 0,
   language TEXT,
-  properties TEXT
+  properties TEXT,
+  embedding TEXT
 )`;
 
 export const CREATE_EDGES = `
@@ -21,6 +22,9 @@ CREATE TABLE IF NOT EXISTS edges (
   relation TEXT NOT NULL,
   confidence TEXT NOT NULL DEFAULT 'EXTRACTED',
   confidence_score REAL NOT NULL DEFAULT 1.0,
+  weight REAL NOT NULL DEFAULT 1.0,
+  reason TEXT,
+  evidence TEXT,
   FOREIGN KEY (source_id) REFERENCES nodes(id),
   FOREIGN KEY (target_id) REFERENCES nodes(id)
 )`;
@@ -47,7 +51,21 @@ CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
   file_path,
   label UNINDEXED,
   content='nodes',
-  content_rowid='rowid'
+  content_rowid='rowid',
+  tokenize='trigram'
+)`;
+
+export const CREATE_EMBEDDINGS = `
+CREATE TABLE IF NOT EXISTS embeddings (
+  node_id TEXT PRIMARY KEY,
+  vector BLOB NOT NULL
+)`;
+
+export const CREATE_WIKI_PAGES = `
+CREATE TABLE IF NOT EXISTS wiki_pages (
+  community_id TEXT PRIMARY KEY,
+  content TEXT NOT NULL,
+  generated_at TEXT NOT NULL
 )`;
 
 export const CREATE_INDEXES = [
@@ -60,6 +78,48 @@ export const CREATE_INDEXES = [
   `CREATE INDEX IF NOT EXISTS idx_edges_confidence ON edges(confidence)`,
 ];
 
+export const CREATE_NODE_PROPERTIES = `
+CREATE TABLE IF NOT EXISTS node_properties (
+  ident TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('text','number','boolean','date','node-ref','closed')),
+  cardinality TEXT NOT NULL DEFAULT 'one' CHECK(cardinality IN ('one','many')),
+  view_context TEXT NOT NULL DEFAULT 'all' CHECK(view_context IN ('all','graph','query','never')),
+  closed_values TEXT,
+  description TEXT,
+  queryable INTEGER NOT NULL DEFAULT 1
+)`;
+
+export const SEED_NODE_PROPERTIES = `
+INSERT OR IGNORE INTO node_properties (ident, type, cardinality, view_context, description, queryable) VALUES
+  ('ua_type',       'closed',  'one',  'query', 'Understand-Anything node type',        1),
+  ('summary',       'text',    'one',  'all',   'LLM-generated description',            1),
+  ('tags',          'text',    'many', 'all',   'Semantic tags from analysis',          1),
+  ('complexity',    'closed',  'one',  'query', 'Code complexity rating',               1),
+  ('layer',         'closed',  'one',  'graph', 'Architectural layer (community name)', 1),
+  ('community_id',  'number',  'one',  'query', 'Community cluster id',                 1),
+  ('language',      'text',    'one',  'query', 'Programming language',                 1),
+  ('is_exported',   'boolean', 'one',  'query', 'Whether symbol is exported',           1)`;
+
+export const CREATE_SUPPRESSIONS = `
+CREATE TABLE IF NOT EXISTS suppressions (
+  id TEXT PRIMARY KEY,
+  file_path TEXT NOT NULL,
+  line INTEGER NOT NULL DEFAULT 0,
+  rule TEXT NOT NULL,
+  added_at TEXT NOT NULL,
+  last_seen_at TEXT
+)`;
+
+export const CREATE_FILE_CACHE = `
+  CREATE TABLE IF NOT EXISTS file_cache (
+    file_path TEXT PRIMARY KEY,
+    content_hash TEXT NOT NULL,
+    last_parsed INTEGER NOT NULL,
+    node_count INTEGER NOT NULL DEFAULT 0,
+    edge_count INTEGER NOT NULL DEFAULT 0
+  )
+`;
+
 export const FTS_SYNC_TRIGGERS = `
 CREATE TRIGGER IF NOT EXISTS nodes_fts_insert AFTER INSERT ON nodes BEGIN
   INSERT INTO nodes_fts(rowid, id, name, norm_label, file_path, label)