@massu/core 0.1.0 → 0.1.2

package/src/cost-tracker.ts

@@ -0,0 +1,355 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import type Database from 'better-sqlite3';
+import type { ToolDefinition, ToolResult } from './tools.ts';
+import type { TranscriptEntry } from './transcript-parser.ts';
+import { getConfig } from './config.ts';
+
+// ============================================================
+// Cost Attribution Tracking
+// ============================================================
+
+/** Prefix a base tool name with the configured tool prefix. */
+function p(baseName: string): string {
+  return `${getConfig().toolPrefix}_${baseName}`;
+}
+
+/** Default model pricing (Claude models). Can be overridden via config.analytics.cost.models */
+const DEFAULT_MODEL_PRICING: Record<string, { input_per_million: number; output_per_million: number; cache_read_per_million?: number; cache_write_per_million?: number }> = {
+  'claude-opus-4-6': { input_per_million: 15.00, output_per_million: 75.00, cache_read_per_million: 1.50, cache_write_per_million: 18.75 },
+  'claude-sonnet-4-6': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
+  'claude-sonnet-4-5': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
+  'claude-haiku-4-5-20251001': { input_per_million: 0.80, output_per_million: 4.00, cache_read_per_million: 0.08, cache_write_per_million: 1.00 },
+  'default': { input_per_million: 3.00, output_per_million: 15.00, cache_read_per_million: 0.30, cache_write_per_million: 3.75 },
+};
+
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  model: string;
+}
+
+export interface CostResult {
+  totalCost: number;
+  inputCost: number;
+  outputCost: number;
+  cacheReadCost: number;
+  cacheWriteCost: number;
+  currency: string;
+}
+
+/**
+ * Get model pricing from config or defaults.
+ */
+function getModelPricing(): Record<string, { input_per_million: number; output_per_million: number; cache_read_per_million?: number; cache_write_per_million?: number }> {
+  return getConfig().analytics?.cost?.models ?? DEFAULT_MODEL_PRICING;
+}
+
+/**
+ * Get currency from config or default.
+ */
+function getCurrency(): string {
+  return getConfig().analytics?.cost?.currency ?? 'USD';
+}
+
+/**
+ * Extract token usage from transcript entries.
+ */
+export function extractTokenUsage(entries: TranscriptEntry[]): TokenUsage {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let model = 'unknown';
+
+  for (const entry of entries) {
+    // Usage and model are present on raw API responses but not typed on TranscriptMessage
+    const msg = entry.message as (Record<string, unknown> | undefined);
+    if (entry.type === 'assistant' && msg?.usage) {
+      const usage = msg.usage as Record<string, number>;
+      inputTokens += usage.input_tokens ?? 0;
+      outputTokens += usage.output_tokens ?? 0;
+      cacheReadTokens += usage.cache_read_input_tokens ?? usage.cache_read_tokens ?? 0;
+      cacheWriteTokens += usage.cache_creation_input_tokens ?? usage.cache_write_tokens ?? 0;
+    }
+    if (entry.type === 'assistant' && msg?.model) {
+      model = msg.model as string;
+    }
+  }
+
+  return { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, model };
+}
+
+/**
+ * Calculate cost from token usage.
+ */
+export function calculateCost(usage: TokenUsage): CostResult {
+  const pricing = getModelPricing();
+  const modelPricing = pricing[usage.model] ?? pricing['default'] ?? pricing['claude-sonnet-4-5'] ?? { input_per_million: 3.00, output_per_million: 15.00 };
+
+  const inputCost = (usage.inputTokens / 1_000_000) * modelPricing.input_per_million;
+  const outputCost = (usage.outputTokens / 1_000_000) * modelPricing.output_per_million;
+  const cacheReadCost = (usage.cacheReadTokens / 1_000_000) * (modelPricing.cache_read_per_million ?? 0);
+  const cacheWriteCost = (usage.cacheWriteTokens / 1_000_000) * (modelPricing.cache_write_per_million ?? 0);
+
+  return {
+    totalCost: inputCost + outputCost + cacheReadCost + cacheWriteCost,
+    inputCost,
+    outputCost,
+    cacheReadCost,
+    cacheWriteCost,
+    currency: getCurrency(),
+  };
+}
+
+/**
+ * Store session cost data.
+ */
+export function storeSessionCost(
+  db: Database.Database,
+  sessionId: string,
+  usage: TokenUsage,
+  cost: CostResult
+): void {
+  const totalTokens = usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
+  db.prepare(`
+    INSERT INTO session_costs
+    (session_id, model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+     total_tokens, estimated_cost_usd)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    sessionId, usage.model,
+    usage.inputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens,
+    totalTokens, cost.totalCost
+  );
+}
+
+/**
+ * Backfill cost data from transcript files.
+ */
+export function backfillSessionCosts(db: Database.Database): number {
+  // Check for sessions without cost data
+  const sessions = db.prepare(`
+    SELECT DISTINCT s.session_id
+    FROM sessions s
+    LEFT JOIN session_costs c ON s.session_id = c.session_id
+    WHERE c.session_id IS NULL
+  `).all() as Array<{ session_id: string }>;
+
+  // Backfilling requires transcript data which may not be available
+  // Return count of sessions that need backfilling
+  return sessions.length;
+}
+
+// ============================================================
+// MCP Tool Definitions & Handlers
+// ============================================================
+
+export function getCostToolDefinitions(): ToolDefinition[] {
+  return [
+    {
+      name: p('cost_session'),
+      description: 'Show cost breakdown for a session. Includes token counts, model pricing, and cost by category.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          session_id: { type: 'string', description: 'Session ID to analyze' },
+        },
+        required: ['session_id'],
+      },
+    },
+    {
+      name: p('cost_trend'),
+      description: 'Cost trend over time. Shows daily/weekly spending and identifies cost drivers.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          days: { type: 'number', description: 'Days to look back (default: 30)' },
+          group_by: { type: 'string', description: 'Group by: day, week (default: day)' },
+        },
+        required: [],
+      },
+    },
+    {
+      name: p('cost_feature'),
+      description: 'Cost attribution by feature. Shows which features consume the most tokens.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          days: { type: 'number', description: 'Days to look back (default: 30)' },
+        },
+        required: [],
+      },
+    },
+  ];
+}
+
+const COST_BASE_NAMES = new Set(['cost_session', 'cost_trend', 'cost_feature']);
+
+export function isCostTool(name: string): boolean {
+  const pfx = getConfig().toolPrefix + '_';
+  const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+  return COST_BASE_NAMES.has(baseName);
+}
+
+export function handleCostToolCall(
+  name: string,
+  args: Record<string, unknown>,
+  memoryDb: Database.Database
+): ToolResult {
+  try {
+    const pfx = getConfig().toolPrefix + '_';
+    const baseName = name.startsWith(pfx) ? name.slice(pfx.length) : name;
+
+    switch (baseName) {
+      case 'cost_session':
+        return handleCostSession(args, memoryDb);
+      case 'cost_trend':
+        return handleCostTrend(args, memoryDb);
+      case 'cost_feature':
+        return handleCostFeature(args, memoryDb);
+      default:
+        return text(`Unknown cost tool: ${name}`);
+    }
+  } catch (error) {
+    return text(`Error in ${name}: ${error instanceof Error ? error.message : String(error)}\n\nUsage: ${p('cost_session')} { session_id: "..." }, ${p('cost_trend')} { days: 30 }`);
+  }
+}
+
+function handleCostSession(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const sessionId = args.session_id as string;
+  if (!sessionId) return text(`Usage: ${p('cost_session')} { session_id: "abc123" } - Show cost breakdown for a specific session.`);
+
+  const cost = db.prepare(
+    'SELECT * FROM session_costs WHERE session_id = ? ORDER BY created_at DESC LIMIT 1'
+  ).get(sessionId) as Record<string, unknown> | undefined;
+
+  if (!cost) {
+    return text(`No cost data found for session ${sessionId}. Cost data is recorded automatically when sessions end via the session-end hook. If the session is still active, data will appear after it completes. Try: ${p('cost_trend')} { days: 30 } to see aggregate cost data instead.`);
+  }
+
+  // Recalculate per-category costs from token counts and model
+  const modelPricing = getModelPricing();
+  const mp = modelPricing[cost.model as string] ?? modelPricing['claude-sonnet-4-5'] ?? { input_per_million: 3.00, output_per_million: 15.00 };
+  const inputCost = ((cost.input_tokens as number) / 1_000_000) * mp.input_per_million;
+  const outputCost = ((cost.output_tokens as number) / 1_000_000) * mp.output_per_million;
+  const cacheReadCost = ((cost.cache_read_tokens as number) / 1_000_000) * (mp.cache_read_per_million ?? 0);
+  const cacheWriteCost = ((cost.cache_write_tokens as number) / 1_000_000) * (mp.cache_write_per_million ?? 0);
+
+  const lines = [
+    `## Session Cost: $${(cost.estimated_cost_usd as number).toFixed(4)}`,
+    `Model: ${cost.model}`,
+    '',
+    '### Token Usage',
+    `| Type | Tokens | Est. Cost |`,
+    `|------|--------|-----------|`,
+    `| Input | ${(cost.input_tokens as number).toLocaleString()} | $${inputCost.toFixed(4)} |`,
+    `| Output | ${(cost.output_tokens as number).toLocaleString()} | $${outputCost.toFixed(4)} |`,
+    `| Cache Read | ${(cost.cache_read_tokens as number).toLocaleString()} | $${cacheReadCost.toFixed(4)} |`,
+    `| Cache Write | ${(cost.cache_write_tokens as number).toLocaleString()} | $${cacheWriteCost.toFixed(4)} |`,
+    `| **Total** | ${(cost.total_tokens as number).toLocaleString()} | **$${(cost.estimated_cost_usd as number).toFixed(4)}** |`,
+  ];
+
+  return text(lines.join('\n'));
+}
+
+function handleCostTrend(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const days = (args.days as number) ?? 30;
+  const groupBy = (args.group_by as string) ?? 'day';
+
+  if (!['day', 'week'].includes(groupBy)) {
+    return text(`Invalid group_by value: "${groupBy}". Use "day" or "week". Example: ${p('cost_trend')} { days: 30, group_by: "week" }`);
+  }
+
+  // Use separate prepared statements to avoid SQL string interpolation.
+  // dateFormat is validated by the allowlist above, but parameterized SQL
+  // is the enterprise-grade approach regardless.
+  const sql = groupBy === 'week'
+    ? `SELECT strftime('%Y-W%W', created_at) as period,
+             COUNT(*) as sessions,
+             SUM(estimated_cost_usd) as total_cost,
+             SUM(total_tokens) as total_tokens,
+             AVG(estimated_cost_usd) as avg_cost
+       FROM session_costs
+       WHERE created_at >= datetime('now', ?)
+       GROUP BY period
+       ORDER BY period ASC`
+    : `SELECT strftime('%Y-%m-%d', created_at) as period,
+             COUNT(*) as sessions,
+             SUM(estimated_cost_usd) as total_cost,
+             SUM(total_tokens) as total_tokens,
+             AVG(estimated_cost_usd) as avg_cost
+       FROM session_costs
+       WHERE created_at >= datetime('now', ?)
+       GROUP BY period
+       ORDER BY period ASC`;
+
+  const rows = db.prepare(sql).all(`-${days} days`) as Array<Record<string, unknown>>;
+
+  if (rows.length === 0) {
+    return text(`No cost data found in the last ${days} days. Cost tracking records token usage automatically at session end via hooks. Ensure session-end hooks are configured in your settings. Try: ${p('cost_session')} { session_id: "..." } to check a specific session.`);
+  }
+
+  const totalCost = rows.reduce((sum, r) => sum + (r.total_cost as number), 0);
+  const totalSessions = rows.reduce((sum, r) => sum + (r.sessions as number), 0);
+
+  const lines = [
+    `## Cost Trend (${days} days)`,
+    `Total: $${totalCost.toFixed(2)} across ${totalSessions} sessions`,
+    `Average per session: $${(totalCost / totalSessions).toFixed(4)}`,
+    '',
+    `### By ${groupBy === 'week' ? 'Week' : 'Day'}`,
+    `| Period | Sessions | Cost | Avg/Session |`,
+    `|--------|----------|------|-------------|`,
+  ];
+
+  for (const row of rows) {
+    lines.push(
+      `| ${row.period} | ${row.sessions} | $${(row.total_cost as number).toFixed(2)} | $${(row.avg_cost as number).toFixed(4)} |`
+    );
+  }
+
+  return text(lines.join('\n'));
+}
+
+function handleCostFeature(args: Record<string, unknown>, db: Database.Database): ToolResult {
+  const days = (args.days as number) ?? 30;
+
+  const rows = db.prepare(`
+    SELECT feature_key, SUM(estimated_cost_usd) as total_cost, SUM(tokens_used) as total_tokens, COUNT(*) as entries
+    FROM feature_costs
+    WHERE created_at >= datetime('now', ?)
+    GROUP BY feature_key
+    ORDER BY total_cost DESC
+  `).all(`-${days} days`) as Array<Record<string, unknown>>;
+
+  if (rows.length === 0) {
+    return text(`No feature cost data found in the last ${days} days. Feature costs are attributed automatically when sessions work on registered features. Ensure features are registered, then costs are tracked per-session. Try: ${p('cost_trend')} { days: 30 } for session-level cost trends instead.`);
+  }
+
+  const totalCost = rows.reduce((sum, r) => sum + (r.total_cost as number), 0);
+
+  const lines = [
+    `## Feature Cost Attribution (${days} days)`,
+    `Total: $${totalCost.toFixed(2)} across ${rows.length} features`,
+    '',
+    '| Feature | Cost | Tokens | Sessions | % of Total |',
+    '|---------|------|--------|----------|------------|',
+  ];
+
+  for (const row of rows) {
+    const pct = totalCost > 0 ? ((row.total_cost as number) / totalCost * 100).toFixed(1) : '0';
+    lines.push(
+      `| ${row.feature_key} | $${(row.total_cost as number).toFixed(2)} | ${(row.total_tokens as number).toLocaleString()} | ${row.entries} | ${pct}% |`
+    );
+  }
+
+  return text(lines.join('\n'));
+}
+
+function text(content: string): ToolResult {
+  return { content: [{ type: 'text', text: content }] };
+}

package/src/db.ts

@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+import Database from 'better-sqlite3';
+import { dirname } from 'path';
+import { existsSync, mkdirSync } from 'fs';
+import { getResolvedPaths } from './config.ts';
+
+/**
+ * Connection to CodeGraph's read-only SQLite database.
+ * We NEVER write to this DB - it belongs to vanilla CodeGraph.
+ */
+export function getCodeGraphDb(): Database.Database {
+  const dbPath = getResolvedPaths().codegraphDbPath;
+  if (!existsSync(dbPath)) {
+    throw new Error(`CodeGraph database not found at ${dbPath}. Run 'npx @colbymchenry/codegraph sync' first.`);
+  }
+  const db = new Database(dbPath, { readonly: true });
+  db.pragma('journal_mode = WAL');
+  return db;
+}
+
+/**
+ * Connection to Massu's supplementary SQLite database.
+ * This stores import edges, tRPC mappings, domain classifications, etc.
+ */
+export function getDataDb(): Database.Database {
+  const dbPath = getResolvedPaths().dataDbPath;
+  const dir = dirname(dbPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  initDataSchema(db);
+  return db;
+}
+
+function initDataSchema(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS massu_imports (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source_file TEXT NOT NULL,
+      target_file TEXT NOT NULL,
+      import_type TEXT NOT NULL CHECK(import_type IN ('named', 'default', 'namespace', 'side_effect', 'dynamic')),
+      imported_names TEXT NOT NULL DEFAULT '[]',
+      line INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_massu_imports_source ON massu_imports(source_file);
+    CREATE INDEX IF NOT EXISTS idx_massu_imports_target ON massu_imports(target_file);
+
+    CREATE TABLE IF NOT EXISTS massu_trpc_procedures (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      router_file TEXT NOT NULL,
+      router_name TEXT NOT NULL,
+      procedure_name TEXT NOT NULL,
+      procedure_type TEXT NOT NULL CHECK(procedure_type IN ('query', 'mutation')),
+      has_ui_caller INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_massu_trpc_router ON massu_trpc_procedures(router_name);
+
+    CREATE TABLE IF NOT EXISTS massu_trpc_call_sites (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      procedure_id INTEGER NOT NULL,
+      file TEXT NOT NULL,
+      line INTEGER NOT NULL DEFAULT 0,
+      call_pattern TEXT NOT NULL,
+      FOREIGN KEY (procedure_id) REFERENCES massu_trpc_procedures(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_massu_call_sites_proc ON massu_trpc_call_sites(procedure_id);
+
+    CREATE TABLE IF NOT EXISTS massu_page_deps (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      page_file TEXT NOT NULL,
+      route TEXT NOT NULL,
+      portal TEXT NOT NULL DEFAULT 'unknown',
+      components TEXT NOT NULL DEFAULT '[]',
+      hooks TEXT NOT NULL DEFAULT '[]',
+      routers TEXT NOT NULL DEFAULT '[]',
+      tables_touched TEXT NOT NULL DEFAULT '[]'
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_massu_page_deps_page ON massu_page_deps(page_file);
+
+    CREATE TABLE IF NOT EXISTS massu_middleware_tree (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file TEXT NOT NULL UNIQUE
+    );
+
+    CREATE TABLE IF NOT EXISTS massu_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    -- ============================================================
+    -- Sentinel: Feature Registry Tables
+    -- ============================================================
+
+    -- Core feature definition
+    CREATE TABLE IF NOT EXISTS massu_sentinel (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_key TEXT UNIQUE NOT NULL,
+      domain TEXT NOT NULL,
+      subdomain TEXT,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT NOT NULL DEFAULT 'active'
+        CHECK(status IN ('planned', 'active', 'deprecated', 'removed')),
+      priority TEXT DEFAULT 'standard'
+        CHECK(priority IN ('critical', 'standard', 'nice-to-have')),
+      portal_scope TEXT DEFAULT '[]',
+      created_at TEXT DEFAULT (datetime('now')),
+      updated_at TEXT DEFAULT (datetime('now')),
+      removed_at TEXT,
+      removed_reason TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sentinel_domain ON massu_sentinel(domain);
+    CREATE INDEX IF NOT EXISTS idx_sentinel_status ON massu_sentinel(status);
+    CREATE INDEX IF NOT EXISTS idx_sentinel_key ON massu_sentinel(feature_key);
+
+    -- Feature-to-component mapping (many-to-many)
+    CREATE TABLE IF NOT EXISTS massu_sentinel_components (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      component_file TEXT NOT NULL,
+      component_name TEXT,
+      role TEXT DEFAULT 'implementation'
+        CHECK(role IN ('implementation', 'ui', 'data', 'utility')),
+      is_primary BOOLEAN DEFAULT 0,
+      UNIQUE(feature_id, component_file, component_name)
+    );
+
+    -- Feature-to-procedure mapping (many-to-many)
+    CREATE TABLE IF NOT EXISTS massu_sentinel_procedures (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      router_name TEXT NOT NULL,
+      procedure_name TEXT NOT NULL,
+      procedure_type TEXT,
+      UNIQUE(feature_id, router_name, procedure_name)
+    );
+
+    -- Feature-to-page mapping (where feature is accessible)
+    CREATE TABLE IF NOT EXISTS massu_sentinel_pages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      page_route TEXT NOT NULL,
+      portal TEXT,
+      UNIQUE(feature_id, page_route, portal)
+    );
+
+    -- Feature dependency graph
+    CREATE TABLE IF NOT EXISTS massu_sentinel_deps (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      depends_on_feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      dependency_type TEXT DEFAULT 'requires'
+        CHECK(dependency_type IN ('requires', 'enhances', 'replaces')),
+      UNIQUE(feature_id, depends_on_feature_id)
+    );
+
+    -- Feature change log (audit trail)
+    CREATE TABLE IF NOT EXISTS massu_sentinel_changelog (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      feature_id INTEGER NOT NULL REFERENCES massu_sentinel(id) ON DELETE CASCADE,
+      change_type TEXT NOT NULL,
+      changed_by TEXT,
+      change_detail TEXT,
+      commit_hash TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sentinel_components_file ON massu_sentinel_components(component_file);
+    CREATE INDEX IF NOT EXISTS idx_sentinel_procedures_router ON massu_sentinel_procedures(router_name);
+    CREATE INDEX IF NOT EXISTS idx_sentinel_pages_route ON massu_sentinel_pages(page_route);
+    CREATE INDEX IF NOT EXISTS idx_sentinel_changelog_feature ON massu_sentinel_changelog(feature_id);
+  `);
+
+  // FTS5 for feature search (separate exec since virtual tables can't be in same batch)
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS massu_sentinel_fts USING fts5(
+      feature_key, title, description, domain, subdomain,
+      content=massu_sentinel, content_rowid=id
+    );
+  `);
+
+  // FTS5 sync triggers
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS massu_sentinel_ai AFTER INSERT ON massu_sentinel BEGIN
+      INSERT INTO massu_sentinel_fts(rowid, feature_key, title, description, domain, subdomain)
+      VALUES (new.id, new.feature_key, new.title, new.description, new.domain, new.subdomain);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS massu_sentinel_ad AFTER DELETE ON massu_sentinel BEGIN
+      INSERT INTO massu_sentinel_fts(massu_sentinel_fts, rowid, feature_key, title, description, domain, subdomain)
+      VALUES ('delete', old.id, old.feature_key, old.title, old.description, old.domain, old.subdomain);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS massu_sentinel_au AFTER UPDATE ON massu_sentinel BEGIN
+      INSERT INTO massu_sentinel_fts(massu_sentinel_fts, rowid, feature_key, title, description, domain, subdomain)
+      VALUES ('delete', old.id, old.feature_key, old.title, old.description, old.domain, old.subdomain);
+      INSERT INTO massu_sentinel_fts(rowid, feature_key, title, description, domain, subdomain)
+      VALUES (new.id, new.feature_key, new.title, new.description, new.domain, new.subdomain);
+    END;
+  `);
+}
+
+/**
+ * Check if Massu indexes are stale compared to CodeGraph timestamps.
+ */
+export function isDataStale(dataDb: Database.Database, codegraphDb: Database.Database): boolean {
+  const lastBuild = dataDb.prepare("SELECT value FROM massu_meta WHERE key = 'last_build_time'").get() as { value: string } | undefined;
+  if (!lastBuild) return true;
+
+  // CodeGraph stores indexed_at as unix timestamp (integer)
+  const latestIndexed = codegraphDb.prepare("SELECT MAX(indexed_at) as latest FROM files").get() as { latest: number } | undefined;
+  if (!latestIndexed?.latest) return true;
+
+  // Convert CodeGraph's unix timestamp to ms and compare with our ISO date
+  return (latestIndexed.latest * 1000) > new Date(lastBuild.value).getTime();
+}
+
+/**
+ * Update the last build timestamp in massu_meta.
+ */
+export function updateBuildTimestamp(dataDb: Database.Database): void {
+  dataDb.prepare("INSERT OR REPLACE INTO massu_meta (key, value) VALUES ('last_build_time', ?)").run(new Date().toISOString());
+}