@monoes/monograph 1.1.0 → 1.2.1

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(`
@@ -23,15 +23,53 @@ export function insertNode(db: Database.Database, node: MonographNode): void {
   );
 }
 
+const INSERT_SQL = `
+    INSERT OR REPLACE INTO nodes
+      (id, label, name, norm_label, file_path, start_line, end_line,
+       community_id, is_exported, language, properties)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `;
+
 export function insertNodes(db: Database.Database, nodes: MonographNode[]): void {
+  if (nodes.length === 0) return;
+  // Prepare once and reuse across all rows — avoids N redundant prepare calls
+  const stmt = db.prepare(INSERT_SQL);
   const insertMany = db.transaction((rows: MonographNode[]) => {
     for (const n of rows) {
-      insertNode(db, n);
+      stmt.run(
+        n.id,
+        n.label,
+        n.name,
+        n.normLabel ?? toNormLabel(n.name),
+        n.filePath ?? null,
+        n.startLine ?? null,
+        n.endLine ?? null,
+        n.communityId ?? null,
+        n.isExported ? 1 : 0,
+        n.language ?? null,
+        n.properties ? JSON.stringify(n.properties) : null,
+      );
     }
   });
   insertMany(nodes);
 }
 
+/** Batch-fetch multiple nodes by ID using a single SQL IN query. Batches at 50 IDs. */
+export function getNodesByIds(db: Database.Database, ids: string[]): MonographNode[] {
+  if (ids.length === 0) return [];
+  const BATCH = 50;
+  const results: MonographNode[] = [];
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const chunk = ids.slice(i, i + BATCH);
+    const placeholders = chunk.map(() => '?').join(',');
+    const rows = db
+      .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
+      .all(...chunk) as Record<string, unknown>[];
+    for (const row of rows) results.push(rowToNode(row));
+  }
+  return results;
+}
+
 export function getNode(db: Database.Database, id: string): MonographNode | undefined {
   const row = db
     .prepare('SELECT * FROM nodes WHERE id = ?')
@@ -55,6 +93,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)

package/src/storage/suppressions.ts

@@ -0,0 +1,145 @@
+import type Database from 'better-sqlite3';
+import { randomUUID } from 'crypto';
+
+export interface Suppression {
+  id: string;
+  filePath: string;
+  line: number;     // 0 = file-wide
+  rule: string;
+  addedAt: string;
+  lastSeenAt?: string;
+}
+
+export interface StaleSuppression extends Suppression {
+  reason: string;  // 'issue_resolved' | 'file_deleted'
+}
+
+// Add a suppression
+export function addSuppression(
+  db: Database.Database,
+  filePath: string,
+  line: number,
+  rule: string,
+): Suppression {
+  const id = randomUUID();
+  const addedAt = new Date().toISOString();
+
+  db.prepare(`
+    INSERT INTO suppressions (id, file_path, line, rule, added_at, last_seen_at)
+    VALUES (?, ?, ?, ?, ?, NULL)
+  `).run(id, filePath, line, rule, addedAt);
+
+  return { id, filePath, line, rule, addedAt };
+}
+
+// List all suppressions (optionally filter by rule or file)
+export function listSuppressions(
+  db: Database.Database,
+  filePath?: string,
+  rule?: string,
+): Suppression[] {
+  let sql = `SELECT id, file_path, line, rule, added_at, last_seen_at FROM suppressions WHERE 1=1`;
+  const params: unknown[] = [];
+
+  if (filePath) {
+    sql += ` AND file_path = ?`;
+    params.push(filePath);
+  }
+  if (rule) {
+    sql += ` AND rule = ?`;
+    params.push(rule);
+  }
+  sql += ` ORDER BY added_at DESC`;
+
+  const rows = db.prepare(sql).all(...params) as {
+    id: string;
+    file_path: string;
+    line: number;
+    rule: string;
+    added_at: string;
+    last_seen_at: string | null;
+  }[];
+
+  return rows.map(r => ({
+    id: r.id,
+    filePath: r.file_path,
+    line: r.line,
+    rule: r.rule,
+    addedAt: r.added_at,
+    ...(r.last_seen_at != null ? { lastSeenAt: r.last_seen_at } : {}),
+  }));
+}
+
+// Remove a suppression
+export function removeSuppression(db: Database.Database, id: string): void {
+  db.prepare(`DELETE FROM suppressions WHERE id = ?`).run(id);
+}
+
+// Check if a finding is suppressed
+// A suppression with line=0 is file-wide and matches any line for the same file+rule
+export function isSuppressed(
+  db: Database.Database,
+  filePath: string,
+  line: number,
+  rule: string,
+): Suppression | null {
+  const row = db.prepare(`
+    SELECT id, file_path, line, rule, added_at, last_seen_at
+    FROM suppressions
+    WHERE file_path = ? AND rule = ? AND (line = 0 OR line = ?)
+    LIMIT 1
+  `).get(filePath, rule, line) as {
+    id: string;
+    file_path: string;
+    line: number;
+    rule: string;
+    added_at: string;
+    last_seen_at: string | null;
+  } | undefined;
+
+  if (!row) return null;
+
+  return {
+    id: row.id,
+    filePath: row.file_path,
+    line: row.line,
+    rule: row.rule,
+    addedAt: row.added_at,
+    ...(row.last_seen_at != null ? { lastSeenAt: row.last_seen_at } : {}),
+  };
+}
+
+// Find stale suppressions
+// A suppression is stale if:
+//   - the file no longer exists in the graph (reason: 'file_deleted')
+//   - the file exists but no active finding matches file+rule (reason: 'issue_resolved')
+export function findStaleSuppressions(
+  db: Database.Database,
+  activeFindings: Array<{ filePath: string; rule: string }>,
+): StaleSuppression[] {
+  const suppressions = listSuppressions(db);
+  if (suppressions.length === 0) return [];
+
+  // Build a set of all file paths in the graph
+  const graphFiles = 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),
+  );
+
+  // Build a set of active finding keys: "filePath::rule"
+  const activeFindingKeys = new Set<string>(
+    activeFindings.map(f => `${f.filePath}::${f.rule}`),
+  );
+
+  const stale: StaleSuppression[] = [];
+
+  for (const s of suppressions) {
+    if (!graphFiles.has(s.filePath)) {
+      stale.push({ ...s, reason: 'file_deleted' });
+    } else if (!activeFindingKeys.has(`${s.filePath}::${s.rule}`)) {
+      stale.push({ ...s, reason: 'issue_resolved' });
+    }
+  }
+
+  return stale;
+}

package/src/storage/unlinked-refs.ts

@@ -0,0 +1,117 @@
+import type Database from 'better-sqlite3';
+
+export interface UnlinkedReference {
+  sourceId: string;
+  sourceName: string;
+  sourceFilePath: string | null;
+  sourceLabel: string;
+  targetName: string;   // the symbol that was mentioned
+  mentionContext: string | null; // snippet of where it was mentioned (from properties.summary)
+  confidence: 'high' | 'medium' | 'low';
+}
+
+/**
+ * Find nodes that mention a target symbol by name in their metadata
+ * (summary, file_path, norm_label) but have no explicit edge to any node
+ * with that name. These are "mentioned but not linked" — latent coupling.
+ *
+ * @param db - open monograph database
+ * @param targetName - symbol name to search for (e.g. "UserService")
+ * @param options.limit - max results (default 50)
+ * @param options.excludeSourceId - skip this node id (avoid self-match)
+ */
+export function findUnlinkedReferences(
+  db: Database.Database,
+  targetName: string,
+  options: { limit?: number; excludeSourceId?: string } = {},
+): UnlinkedReference[] {
+  const limit = options.limit ?? 50;
+  const excludeSourceId = options.excludeSourceId ?? '';
+  const pattern = `%${targetName}%`;
+
+  // Step 1: Find all node IDs that already have an explicit edge to any node
+  // whose name matches targetName — these are "already linked" and excluded.
+  const linkedRows = db.prepare(`
+    SELECT DISTINCT e.source_id FROM edges e
+    JOIN nodes n ON n.id = e.target_id
+    WHERE n.name = ?
+  `).all(targetName) as { source_id: string }[];
+
+  const linkedIds = new Set(linkedRows.map(r => r.source_id));
+
+  // Step 2: Find nodes that mention targetName in name, norm_label, or
+  // properties JSON — but are NOT in the linked set and not self.
+  const rows = db.prepare(`
+    SELECT n.id, n.name, n.file_path, n.label, n.properties
+    FROM nodes n
+    WHERE (
+      n.name LIKE ? OR
+      n.norm_label LIKE ? OR
+      (n.properties IS NOT NULL AND n.properties LIKE ?)
+    )
+    AND n.name != ?
+    LIMIT ?
+  `).all(pattern, pattern, pattern, targetName, limit * 4) as Array<{
+    id: string;
+    name: string;
+    file_path: string | null;
+    label: string;
+    properties: string | null;
+  }>;
+
+  const results: UnlinkedReference[] = [];
+
+  for (const row of rows) {
+    // Skip nodes that already have an explicit edge to the target
+    if (linkedIds.has(row.id)) continue;
+    // Skip the excluded node (e.g. the target node itself)
+    if (excludeSourceId && row.id === excludeSourceId) continue;
+
+    // Determine confidence and extract mention context
+    let confidence: 'high' | 'medium' | 'low';
+    let mentionContext: string | null = null;
+
+    if (row.name.includes(targetName)) {
+      // Target name appears in the symbol's own name
+      confidence = 'high';
+    } else if (row.file_path !== null && row.file_path.includes(targetName)) {
+      // Appears in the file path
+      confidence = 'medium';
+    } else {
+      // Only in properties.summary
+      confidence = 'low';
+    }
+
+    // Extract a 100-char context window from properties.summary if available
+    if (row.properties !== null) {
+      try {
+        const props = JSON.parse(row.properties) as Record<string, unknown>;
+        const summary = typeof props['summary'] === 'string' ? props['summary'] : null;
+        if (summary !== null && summary.includes(targetName)) {
+          const idx = summary.indexOf(targetName);
+          const start = Math.max(0, idx - 50);
+          const end = Math.min(summary.length, idx + targetName.length + 50);
+          mentionContext = summary.slice(start, end);
+          // Refine confidence: if we previously set 'low' due to no name/path match,
+          // and properties match confirms it, keep 'low'. Otherwise stay as-is.
+        }
+      } catch {
+        // Malformed JSON — skip
+      }
+    }
+
+    results.push({
+      sourceId: row.id,
+      sourceName: row.name,
+      sourceFilePath: row.file_path,
+      sourceLabel: row.label,
+      targetName,
+      mentionContext,
+      confidence,
+    });
+
+    if (results.length >= limit) break;
+  }
+
+  return results;
+}

package/src/types.ts

@@ -5,7 +5,8 @@ export type NodeLabel =
   | 'Variable' | 'Struct' | 'Enum' | 'Macro' | 'Typedef' | 'Union'
   | 'Namespace' | 'Trait' | 'Impl' | 'TypeAlias' | 'Const' | 'Static'
   | 'Property' | 'Record' | 'Delegate' | 'Annotation' | 'Constructor'
-  | 'Template' | 'Module' | 'Process' | 'Route' | 'Community' | 'Concept';
+  | 'Template' | 'Module' | 'Process' | 'Route' | 'Community' | 'Concept'
+  | 'Section' | 'Document' | 'Tool' | 'Entity' | 'Field';
 
 export const SYMBOL_NODE_LABELS = new Set<NodeLabel>([
   'Function', 'Class', 'Method', 'Interface', 'Variable', 'Struct', 'Enum',
@@ -17,10 +18,15 @@ export const SYMBOL_NODE_LABELS = new Set<NodeLabel>([
 // ── Edge relations ────────────────────────────────────────────────────────────
 
 export type EdgeRelation =
-  | 'CONTAINS' | 'DEFINES' | 'CALLS' | 'IMPORTS' | 'EXTENDS' | 'IMPLEMENTS'
+  | 'CONTAINS' | 'DEFINES' | 'CALLS' | 'IMPORTS' | 'RE_EXPORTS' | 'EXTENDS' | 'IMPLEMENTS'
   | 'HAS_METHOD' | 'HAS_PROPERTY' | 'ACCESSES' | 'METHOD_OVERRIDES'
   | 'METHOD_IMPLEMENTS' | 'MEMBER_OF' | 'STEP_IN_PROCESS' | 'HANDLES_ROUTE'
-  | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES';
+  | 'FETCHES' | 'HANDLES_TOOL' | 'ENTRY_POINT_OF' | 'WRAPS' | 'QUERIES'
+  | 'REFERENCES' | 'PARENT_SECTION' | 'TAGGED_AS' | 'HAS_FIELD'
+  // Doc KG — contextual proximity
+  | 'CO_OCCURS'
+  // Doc KG — LLM-inferred semantic relations
+  | 'DESCRIBES' | 'CAUSES' | 'CONTRASTS_WITH' | 'PART_OF' | 'RELATED_TO' | 'USES' | 'STRUCTURALLY_SIMILAR';
 
 // ── Confidence ────────────────────────────────────────────────────────────────
 
@@ -45,9 +51,18 @@ export interface MonographNode {
   communityId?: number;
   isExported: boolean;
   language?: string;
+  reachabilityRole?: 'runtime' | 'test' | 'support' | 'unreachable';
   properties?: Record<string, unknown>;
 }
 
+// ── Evidence ──────────────────────────────────────────────────────────────────
+
+export interface EvidenceEntry {
+  kind: string;      // e.g., 'import', 'call', 'heuristic', 'inferred'
+  weight: number;    // 0-1
+  note?: string;     // human-readable explanation
+}
+
 // ── Edges ─────────────────────────────────────────────────────────────────────
 
 export interface MonographEdge {
@@ -57,6 +72,9 @@ export interface MonographEdge {
   relation: EdgeRelation;
   confidence: EdgeConfidence;
   confidenceScore: number;
+  weight?: number;
+  reason?: string;
+  evidence?: EvidenceEntry[];
 }
 
 // ── Communities ───────────────────────────────────────────────────────────────
@@ -76,6 +94,22 @@ export interface GodNode extends MonographNode {
   outDegree: number;
 }
 
+// ── Complexity metrics ────────────────────────────────────────────────────────
+
+export interface ComplexityMetrics {
+  cyclomaticComplexity: number;
+  cognitiveComplexity: number;
+  linesOfCode: number;
+  paramCount: number;
+}
+
+export interface CrapScore {
+  cc: number;
+  coverage: number;   // 0-1
+  score: number;      // CC² × (1-coverage)³ + CC
+  risk: 'low' | 'medium' | 'high' | 'critical';
+}
+
 // ── Surprising connections ────────────────────────────────────────────────────
 
 export interface SurprisingConnection {
@@ -91,7 +125,39 @@ export type SuggestedQuestion =
   | { type: 'bridge_node'; node: MonographNode; commA: number; commB: number }
   | { type: 'verify_inferred'; edge: MonographEdge; inferredFrom: string }
   | { type: 'isolated_nodes'; nodes: MonographNode[]; reason: string }
-  | { type: 'low_cohesion'; community: MonographCommunity };
+  | { type: 'low_cohesion'; community: MonographCommunity }
+  | { type: 'no_signal'; edge: MonographEdge; reason: string }
+  | { type: 'thin_community'; communityId: number; memberCount: number; reason: string };
+
+// ── Finding actions (structured remediation steps) ────────────────────────────
+
+export type FindingActionType =
+  | 'investigate'     // read/understand the file
+  | 'refactor'        // reduce complexity or coupling
+  | 'delete'          // safe to remove
+  | 'add-test'        // add test coverage
+  | 'add-import'      // add missing import edge
+  | 'extract'         // extract to separate module
+  | 'review'          // human review required
+  | 'add-edge';       // add explicit graph relationship
+
+export interface FindingAction {
+  type: FindingActionType;
+  file?: string;       // target file path
+  symbol?: string;     // specific symbol/export name
+  description: string; // human-readable instruction
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface AnnotatedFinding {
+  title: string;
+  severity: 'error' | 'warning' | 'info';
+  nodeId?: string;
+  nodeName?: string;
+  filePath?: string | null;
+  introduced?: boolean;
+  actions: FindingAction[];
+}
 
 // ── ID generation ─────────────────────────────────────────────────────────────
 

package/src/validation/extraction-validator.ts

@@ -0,0 +1,54 @@
+import type { MonographNode, MonographEdge, EdgeConfidence, NodeLabel } from '../types.js';
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const VALID_LABELS = new Set<NodeLabel>([
+  'File', 'Folder', 'Function', 'Class', 'Method', 'Interface',
+  'Variable', 'Struct', 'Enum', 'Macro', 'Typedef', 'Union',
+  'Namespace', 'Trait', 'Impl', 'TypeAlias', 'Const', 'Static',
+  'Property', 'Record', 'Delegate', 'Annotation', 'Constructor',
+  'Template', 'Module', 'Process', 'Route', 'Community', 'Concept',
+  'Document', 'Tool', 'Entity', 'Field',
+]);
+
+const VALID_CONFIDENCES = new Set<EdgeConfidence>(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
+
+export function validateExtraction(
+  nodes: MonographNode[],
+  edges: MonographEdge[],
+): ValidationResult {
+  const errors: string[] = [];
+  const nodeIds = new Set(nodes.map(n => n.id));
+
+  for (const n of nodes) {
+    if (!n.id) errors.push(`Node missing id: ${JSON.stringify(n.name)}`);
+    if (!n.name) errors.push(`Node ${n.id} missing name`);
+    if (!VALID_LABELS.has(n.label as NodeLabel)) {
+      errors.push(`Node ${n.id} has invalid label: ${n.label}`);
+    }
+    if (typeof n.isExported !== 'boolean') {
+      errors.push(`Node ${n.id}: isExported must be boolean`);
+    }
+  }
+
+  for (const e of edges) {
+    if (!e.id) errors.push(`Edge missing id`);
+    if (!nodeIds.has(e.sourceId)) {
+      errors.push(`Edge ${e.id}: sourceId '${e.sourceId}' references unknown node`);
+    }
+    if (!nodeIds.has(e.targetId)) {
+      errors.push(`Edge ${e.id}: targetId '${e.targetId}' references unknown node`);
+    }
+    if (!VALID_CONFIDENCES.has(e.confidence)) {
+      errors.push(`Edge ${e.id}: invalid confidence '${e.confidence}'`);
+    }
+    if (typeof e.confidenceScore !== 'number') {
+      errors.push(`Edge ${e.id}: confidenceScore must be number`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}