@cleocode/core 2026.4.30 → 2026.4.31

package/src/store/brain-schema.ts

@@ -94,6 +94,12 @@ export const brainDecisions = sqliteTable(
     contextEpicId: text('context_epic_id'), // soft FK to tasks.id in tasks.db
     contextTaskId: text('context_task_id'), // soft FK to tasks.id in tasks.db
     contextPhase: text('context_phase'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from confidence, content richness, and context.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
   },
@@ -103,6 +109,7 @@ export const brainDecisions = sqliteTable(
     index('idx_brain_decisions_outcome').on(table.outcome),
     index('idx_brain_decisions_context_epic').on(table.contextEpicId),
     index('idx_brain_decisions_context_task').on(table.contextTaskId),
+    index('idx_brain_decisions_quality').on(table.qualityScore),
   ],
 );
 
@@ -123,11 +130,18 @@ export const brainPatterns = sqliteTable(
     examplesJson: text('examples_json').default('[]'),
     extractedAt: text('extracted_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from type, content richness, and examples.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
   },
   (table) => [
     index('idx_brain_patterns_type').on(table.type),
     index('idx_brain_patterns_impact').on(table.impact),
     index('idx_brain_patterns_frequency').on(table.frequency),
+    index('idx_brain_patterns_quality').on(table.qualityScore),
   ],
 );
 
@@ -145,10 +159,17 @@ export const brainLearnings = sqliteTable(
     applicableTypesJson: text('applicable_types_json'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from confidence, actionability, and content richness.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
   },
   (table) => [
     index('idx_brain_learnings_confidence').on(table.confidence),
     index('idx_brain_learnings_actionable').on(table.actionable),
+    index('idx_brain_learnings_quality').on(table.qualityScore),
   ],
 );
 
@@ -176,6 +197,12 @@ export const brainObservations = sqliteTable(
     agent: text('agent'), // nullable — null for legacy observations
     contentHash: text('content_hash'), // SHA-256 prefix for dedup
     discoveryTokens: integer('discovery_tokens'), // cost to produce this observation
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from content richness and title length.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
   },
@@ -191,6 +218,8 @@ export const brainObservations = sqliteTable(
     index('idx_brain_observations_type_project').on(table.type, table.project),
     // T417: agent provenance index for memory.find --agent filter
     index('idx_brain_observations_agent').on(table.agent),
+    // T531: quality score filter index
+    index('idx_brain_observations_quality').on(table.qualityScore),
   ],
 );
 
@@ -244,41 +273,163 @@ export const brainSchemaMeta = sqliteTable('brain_schema_meta', {
   value: text('value').notNull(),
 });
 
-// === PAGEINDEX GRAPH TABLES (T5160) ===
+// === PAGEINDEX GRAPH TABLES (T5160, expanded T528) ===
 
-/** Node types for PageIndex graph. */
-export const BRAIN_NODE_TYPES = ['task', 'doc', 'file', 'concept'] as const;
+/**
+ * Node types for the graph-native memory model.
+ * Mirrors typed tables (decision, pattern, learning, observation, sticky),
+ * adds task provenance (task, session, epic), codebase bridging (file, symbol),
+ * and abstract/synthesized types (concept, summary).
+ */
+export const BRAIN_NODE_TYPES = [
+  // Memory entity types (mirror typed tables)
+  'decision',
+  'pattern',
+  'learning',
+  'observation',
+  'sticky',
+  // Task provenance (soft FK into tasks.db)
+  'task',
+  'session',
+  'epic',
+  // Codebase integration (bridge to nexus.db code_index)
+  'file',
+  'symbol',
+  // Abstract / synthesized
+  'concept',
+  'summary',
+] as const;
 
-/** Edge types for PageIndex graph. */
-export const BRAIN_EDGE_TYPES = ['depends_on', 'relates_to', 'implements', 'documents'] as const;
+/** Discriminated union of all supported brain graph node types. */
+export type BrainNodeType = (typeof BRAIN_NODE_TYPES)[number];
 
-/** Documents/concepts as graph nodes for cross-document linking. */
+/**
+ * Edge types for the graph-native memory model.
+ * Covers provenance/derivation, semantic relationships, structural links,
+ * and graph bridging between memory entities and codebase nodes.
+ */
+export const BRAIN_EDGE_TYPES = [
+  // Provenance / derivation
+  'derived_from', // learning ← derived_from ← observation
+  'produced_by', // observation ← produced_by ← session
+  'informed_by', // decision ← informed_by ← pattern
+  // Semantic relationship
+  'supports', // observation → supports → decision
+  'contradicts', // observation → contradicts → decision
+  'supersedes', // decision → supersedes → decision (older)
+  'applies_to', // decision/pattern → applies_to → task/file/symbol
+  // Structural
+  'documents', // observation → documents → symbol/file
+  'summarizes', // summary → summarizes → observation (consolidation)
+  'part_of', // task → part_of → epic
+  // Graph bridging (memory ↔ code)
+  'references', // observation → references → symbol
+  'modified_by', // file → modified_by → session
+] as const;
+
+/** Discriminated union of all supported brain graph edge types. */
+export type BrainEdgeType = (typeof BRAIN_EDGE_TYPES)[number];
+
+/**
+ * Graph nodes table — the traversable knowledge graph layer.
+ *
+ * Every entity row in a typed table (decisions, patterns, learnings,
+ * observations) gets a corresponding node here. The typed table row is
+ * the source of truth; the graph node is the index entry for traversal
+ * and cross-entity reasoning.
+ *
+ * Node ID convention: '<type>:<source-id>'
+ * Examples: 'decision:D-abc123', 'observation:O-mntphoj6-0',
+ *           'task:T523', 'symbol:src/store/brain-schema.ts::brainPageNodes'
+ */
 export const brainPageNodes = sqliteTable(
   'brain_page_nodes',
   {
-    id: text('id').primaryKey(), // 'task:T5241', 'doc:BRAIN-SPEC', 'file:src/store/brain-schema.ts'
+    /** Stable composite ID: '<type>:<source-id>' */
+    id: text('id').primaryKey(),
+
+    /** Discriminated type from BRAIN_NODE_TYPES. */
     nodeType: text('node_type', { enum: BRAIN_NODE_TYPES }).notNull(),
+
+    /** Human-readable label (title, name, or generated summary). */
     label: text('label').notNull(),
-    metadataJson: text('metadata_json'), // JSON blob for extensible metadata
+
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical).
+     * Derived from: source confidence, edge density, age decay, agent provenance.
+     * Default 0.5 for unknown provenance; 0.0 triggers exclusion from traversal.
+     */
+    qualityScore: real('quality_score').notNull().default(0.5),
+
+    /**
+     * SHA-256 prefix (first 16 hex chars) of the canonical content.
+     * Computed at insert time; duplicate hashes are rejected.
+     * Null for external references (task, session, symbol nodes).
+     */
+    contentHash: text('content_hash'),
+
+    /**
+     * ISO 8601 timestamp of last activity on this node.
+     * Updated when new edges are added, quality changes, or content is revised.
+     */
+    lastActivityAt: text('last_activity_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Extensible JSON metadata blob — type-specific payload.
+     * decision: { type, confidence, outcome }
+     * observation: { sourceType, agent, sessionId }
+     * symbol: { filePath, kind, startLine, endLine, language }
+     * task: { status, priority, epicId }
+     */
+    metadataJson: text('metadata_json'),
+
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
+    updatedAt: text('updated_at'),
   },
-  (table) => [index('idx_brain_nodes_type').on(table.nodeType)],
+  (table) => [
+    index('idx_brain_nodes_type').on(table.nodeType),
+    index('idx_brain_nodes_quality').on(table.qualityScore),
+    index('idx_brain_nodes_content_hash').on(table.contentHash),
+    index('idx_brain_nodes_last_activity').on(table.lastActivityAt),
+  ],
 );
 
-/** Directed links between graph nodes. */
+/**
+ * Graph edges table — directed, typed, weighted, provenance-aware links
+ * between brain_page_nodes entries (or external nexus node IDs).
+ *
+ * The composite primary key (fromId, toId, edgeType) prevents duplicate
+ * edges of the same type between the same pair of nodes.
+ */
 export const brainPageEdges = sqliteTable(
   'brain_page_edges',
   {
-    fromId: text('from_id').notNull(),
-    toId: text('to_id').notNull(),
+    fromId: text('from_id').notNull(), // brain_page_nodes.id
+    toId: text('to_id').notNull(), // brain_page_nodes.id or nexus node id
     edgeType: text('edge_type', { enum: BRAIN_EDGE_TYPES }).notNull(),
-    weight: real('weight').default(1.0),
+
+    /**
+     * Edge weight / confidence: 0.0 – 1.0.
+     * Semantic edges use extractor confidence (similarity score).
+     * Structural edges use 1.0 (deterministic).
+     * Contradiction edges store the overlap score that triggered detection.
+     */
+    weight: real('weight').notNull().default(1.0),
+
+    /**
+     * Human-readable note on why this edge was emitted.
+     * Examples: 'auto:task-complete' | 'auto:session-end' |
+     *           'auto:contradiction-detected' | 'auto:consolidation' | 'manual'
+     */
+    provenance: text('provenance'),
+
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
   },
   (table) => [
     primaryKey({ columns: [table.fromId, table.toId, table.edgeType] }),
     index('idx_brain_edges_from').on(table.fromId),
     index('idx_brain_edges_to').on(table.toId),
+    index('idx_brain_edges_type').on(table.edgeType),
   ],
 );
 
@@ -300,3 +451,4 @@ export type BrainPageEdgeRow = typeof brainPageEdges.$inferSelect;
 export type NewBrainPageEdgeRow = typeof brainPageEdges.$inferInsert;
 export type BrainStickyNoteRow = typeof brainStickyNotes.$inferSelect;
 export type NewBrainStickyNoteRow = typeof brainStickyNotes.$inferInsert;
+// BrainNodeType and BrainEdgeType are declared alongside their enum arrays above.

package/src/store/brain-sqlite.ts

@@ -142,6 +142,30 @@ export function isBrainVecLoaded(): boolean {
   return _vecLoaded;
 }
 
+/**
+ * Initialize the default embedding provider when brain.embedding.enabled is true.
+ *
+ * Called asynchronously after getBrainDb() completes its synchronous setup.
+ * Uses dynamic import to avoid circular dependencies and keep the heavy
+ * @huggingface/transformers bundle out of the critical startup path.
+ *
+ * Best-effort: errors are swallowed by the caller so DB access is never blocked.
+ *
+ * @task T539
+ */
+async function initEmbeddingProvider(cwd?: string): Promise<void> {
+  try {
+    const { loadConfig } = await import('../config.js');
+    const config = await loadConfig(cwd);
+    if (config.brain?.embedding?.enabled) {
+      const { initDefaultProvider } = await import('../memory/brain-embedding.js');
+      await initDefaultProvider();
+    }
+  } catch {
+    // Config load or provider init failed — non-fatal, embedding stays unavailable
+  }
+}
+
 /**
  * Initialize the brain.db SQLite database (lazy, singleton).
  * Creates the database file and tables if they don't exist.
@@ -200,6 +224,17 @@ export async function getBrainDb(cwd?: string): Promise<NodeSQLiteDatabase<typeo
 
     // Set singleton only after migrations complete
     _db = db;
+
+    // Wire the default embedding provider when vec is loaded and embedding is enabled.
+    // Best-effort, async, never blocks DB access. (T539)
+    if (_vecLoaded) {
+      setImmediate(() => {
+        initEmbeddingProvider(cwd).catch(() => {
+          // Non-fatal — embedding will be unavailable until next startup
+        });
+      });
+    }
+
     return db;
   })();
 

package/src/store/nexus-schema.ts

@@ -1,14 +1,17 @@
 /**
  * Drizzle ORM schema for CLEO nexus.db (SQLite via node:sqlite + sqlite-proxy).
  *
- * Tables: project_registry, nexus_audit_log, nexus_schema_meta
- * Stores cross-project registry and audit infrastructure for the Nexus domain.
+ * Tables: project_registry, nexus_audit_log, nexus_schema_meta,
+ *         nexus_nodes, nexus_relations
+ * Stores cross-project registry and audit infrastructure for the Nexus domain,
+ * plus the code intelligence graph layer (nodes + directed edges).
  *
  * @task T5365
+ * @task T529
  */
 
 import { sql } from 'drizzle-orm';
-import { index, integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { index, integer, real, sqliteTable, text } from 'drizzle-orm/sqlite-core';
 
 // === PROJECT_REGISTRY TABLE ===
 
@@ -75,6 +78,253 @@ export const nexusSchemaMeta = sqliteTable('nexus_schema_meta', {
   value: text('value').notNull(),
 });
 
+// === NEXUS_NODES TABLE ===
+
+/**
+ * All node kind values — matches GraphNodeKind in @cleocode/contracts.
+ *
+ * Kept as a const tuple for use in Drizzle enum column definitions.
+ * The ordering is intentional: structural → module → callable → type →
+ * value-level → language-specific → graph-level → legacy.
+ */
+export const NEXUS_NODE_KINDS = [
+  // Structural
+  'file',
+  'folder',
+  // Module-level
+  'module',
+  'namespace',
+  // Callable
+  'function',
+  'method',
+  'constructor',
+  // Type hierarchy
+  'class',
+  'interface',
+  'struct',
+  'trait',
+  'impl',
+  'type_alias',
+  'enum',
+  // Value-level
+  'property',
+  'constant',
+  'variable',
+  'static',
+  'record',
+  'delegate',
+  // Language-specific constructs
+  'macro',
+  'union',
+  'typedef',
+  'annotation',
+  'template',
+  // Graph-level (synthetic nodes from analysis phases)
+  'community',
+  'process',
+  'route',
+  // External references
+  'tool',
+  'section',
+  // Legacy (kept for T506 compatibility)
+  'import',
+  'export',
+  'type',
+] as const;
+
+/** TypeScript type derived from NEXUS_NODE_KINDS. */
+export type NexusNodeKind = (typeof NEXUS_NODE_KINDS)[number];
+
+/**
+ * Graph nodes table — one row per symbol or structural element.
+ *
+ * Stores all code intelligence graph nodes indexed per project.
+ * Synthetic nodes (community, process) share this table with
+ * source-derived nodes (function, class, file).
+ *
+ * Both this table and `code_index` are populated from the same parse pass.
+ * They serve complementary roles — do NOT merge them.
+ *
+ * @task T529
+ */
+export const nexusNodes = sqliteTable(
+  'nexus_nodes',
+  {
+    /** Stable node ID. Format: `<filePath>::<name>` for symbols,
+     *  `<filePath>` for file nodes, `community:<n>` for community nodes,
+     *  `process:<slug>` for execution flow nodes. */
+    id: text('id').primaryKey(),
+
+    /** Foreign key to project_registry.project_id. Scopes the node. */
+    projectId: text('project_id').notNull(),
+
+    /** Node kind from GraphNodeKind union. */
+    kind: text('kind', { enum: NEXUS_NODE_KINDS }).notNull(),
+
+    /** Human-readable label for display. For symbols, same as name.
+     *  For communities, the inferred folder label. For processes, the
+     *  entry point function name. */
+    label: text('label').notNull(),
+
+    /** Symbol name as it appears in source code. Null for file/folder nodes. */
+    name: text('name'),
+
+    /** File path relative to project root. Null for community/process nodes. */
+    filePath: text('file_path'),
+
+    /** Start line in source file (1-based). Null for structural nodes. */
+    startLine: integer('start_line'),
+
+    /** End line in source file (1-based). Null for structural nodes. */
+    endLine: integer('end_line'),
+
+    /** Source language (typescript, python, go, rust, etc.). */
+    language: text('language'),
+
+    /** Whether the symbol is publicly exported from its module. */
+    isExported: integer('is_exported', { mode: 'boolean' }).notNull().default(false),
+
+    /** Parent node ID for nested symbols (e.g., method inside class).
+     *  References nexus_nodes.id in the same project. Soft FK. */
+    parentId: text('parent_id'),
+
+    /** JSON array of parameter name strings for functions/methods.
+     *  Stored as `["param1","param2"]`. Null if not applicable. */
+    parametersJson: text('parameters_json'),
+
+    /** Return type annotation text (e.g., "Promise<void>"). */
+    returnType: text('return_type'),
+
+    /** First line of the TSDoc/JSDoc comment for this symbol. */
+    docSummary: text('doc_summary'),
+
+    /** Community membership ID — references the community node's id.
+     *  Set during Phase 4.5 community detection. Null until then. */
+    communityId: text('community_id'),
+
+    /** JSON blob for kind-specific metadata.
+     *  For `process` nodes: `{"stepCount": 7, "entryScore": 0.92}`.
+     *  For `community` nodes: `{"memberCount": 14, "topFolders": ["src/core"]}`.
+     *  For `route` nodes: `{"method": "GET", "path": "/api/v1/tasks"}`.
+     *  For all others: null. */
+    metaJson: text('meta_json'),
+
+    /** ISO 8601 timestamp when this node was last indexed. */
+    indexedAt: text('indexed_at').notNull().default(sql`(datetime('now'))`),
+  },
+  (table) => [
+    index('idx_nexus_nodes_project').on(table.projectId),
+    index('idx_nexus_nodes_kind').on(table.kind),
+    index('idx_nexus_nodes_file').on(table.filePath),
+    index('idx_nexus_nodes_name').on(table.name),
+    index('idx_nexus_nodes_project_kind').on(table.projectId, table.kind),
+    index('idx_nexus_nodes_project_file').on(table.projectId, table.filePath),
+    index('idx_nexus_nodes_community').on(table.communityId),
+    index('idx_nexus_nodes_parent').on(table.parentId),
+    index('idx_nexus_nodes_exported').on(table.isExported),
+  ],
+);
+
+// === NEXUS_RELATIONS TABLE ===
+
+/**
+ * All relation type values — matches GraphRelationType in @cleocode/contracts.
+ *
+ * Kept as a const tuple for use in Drizzle enum column definitions.
+ */
+export const NEXUS_RELATION_TYPES = [
+  // Structural
+  'contains',
+  // Definition / usage
+  'defines',
+  'imports',
+  'accesses',
+  // Callable
+  'calls',
+  // Type hierarchy
+  'extends',
+  'implements',
+  'method_overrides',
+  'method_implements',
+  // Class structure
+  'has_method',
+  'has_property',
+  // Graph-level (synthetic, from analysis phases)
+  'member_of', // symbol → community
+  'step_in_process', // symbol → process
+  // Web / API
+  'handles_route', // function → route node
+  'fetches', // function → external API
+  // Tool / agent
+  'handles_tool',
+  'entry_point_of', // function → process
+  // Wrapping / delegation
+  'wraps',
+  // Data access
+  'queries',
+  // Cross-graph (brain link)
+  'documents', // brain_page_node → nexus_nodes
+  'applies_to', // brain_page_node → nexus_nodes
+] as const;
+
+/** TypeScript type derived from NEXUS_RELATION_TYPES. */
+export type NexusRelationType = (typeof NEXUS_RELATION_TYPES)[number];
+
+/**
+ * Graph relations table — one row per directed edge.
+ *
+ * All graph traversal (impact, context, process detection) reads from
+ * this table after ingestion completes.
+ *
+ * Source and target reference nexus_nodes.id. They are soft FKs —
+ * unresolved targets (e.g., external packages) are stored as raw specifiers.
+ *
+ * @task T529
+ */
+export const nexusRelations = sqliteTable(
+  'nexus_relations',
+  {
+    /** UUID v4 row identifier. */
+    id: text('id').primaryKey(),
+
+    /** Foreign key to project_registry.project_id. */
+    projectId: text('project_id').notNull(),
+
+    /** Source node ID (nexus_nodes.id). */
+    sourceId: text('source_id').notNull(),
+
+    /** Target node ID (nexus_nodes.id) or raw module specifier for
+     *  unresolved imports. Example: `@cleocode/contracts` or
+     *  `src/core/parser.ts::parseFile`. */
+    targetId: text('target_id').notNull(),
+
+    /** Semantic relation type. */
+    type: text('type', { enum: NEXUS_RELATION_TYPES }).notNull(),
+
+    /** Extractor confidence (0.0 to 1.0). */
+    confidence: real('confidence').notNull(),
+
+    /** Human-readable note explaining why this relation was emitted. */
+    reason: text('reason'),
+
+    /** Step index within an execution flow (for step_in_process relations). */
+    step: integer('step'),
+
+    /** ISO 8601 timestamp when this relation was last indexed. */
+    indexedAt: text('indexed_at').notNull().default(sql`(datetime('now'))`),
+  },
+  (table) => [
+    index('idx_nexus_relations_project').on(table.projectId),
+    index('idx_nexus_relations_source').on(table.sourceId),
+    index('idx_nexus_relations_target').on(table.targetId),
+    index('idx_nexus_relations_type').on(table.type),
+    index('idx_nexus_relations_project_type').on(table.projectId, table.type),
+    index('idx_nexus_relations_source_type').on(table.sourceId, table.type),
+    index('idx_nexus_relations_target_type').on(table.targetId, table.type),
+    index('idx_nexus_relations_confidence').on(table.confidence),
+  ],
+);
+
 // === TYPE EXPORTS ===
 
 export type ProjectRegistryRow = typeof projectRegistry.$inferSelect;
@@ -83,3 +333,7 @@ export type NexusAuditLogRow = typeof nexusAuditLog.$inferSelect;
 export type NewNexusAuditLogRow = typeof nexusAuditLog.$inferInsert;
 export type NexusSchemaMetaRow = typeof nexusSchemaMeta.$inferSelect;
 export type NewNexusSchemaMetaRow = typeof nexusSchemaMeta.$inferInsert;
+export type NexusNodeRow = typeof nexusNodes.$inferSelect;
+export type NewNexusNodeRow = typeof nexusNodes.$inferInsert;
+export type NexusRelationRow = typeof nexusRelations.$inferSelect;
+export type NewNexusRelationRow = typeof nexusRelations.$inferInsert;