@cleocode/core 2026.4.49 → 2026.4.51

package/src/memory/decision-cross-link.ts

@@ -0,0 +1,276 @@
+/**
+ * Decision cross-link module for CLEO BRAIN.
+ *
+ * Extracts file paths and symbol names referenced in a decision's text and
+ * rationale, then creates `affects` edges from the decision graph node to
+ * matching `file` / `symbol` nodes in brain_page_nodes.  This implements
+ * the cross-substrate edge described in
+ * docs/plans/brain-synaptic-visualization-research.md §3.2.
+ *
+ * All database operations are best-effort — they never throw or block the
+ * caller.  Nodes for referenced files / symbols are upserted on demand so
+ * the graph remains consistent even when the target has not yet been
+ * independently indexed.
+ *
+ * @task T626
+ * @epic T626
+ */
+
+import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/** A reference extracted from a decision or rationale string. */
+export interface ExtractedRef {
+  /** Raw text that matched. */
+  raw: string;
+  /** Resolved graph node ID: 'file:<path>' or 'symbol:<name>'. */
+  nodeId: string;
+  /** Discriminated node type. */
+  nodeType: 'file' | 'symbol';
+  /** Human-readable label for the graph node. */
+  label: string;
+}
+
+/**
+ * Regex patterns used to locate file paths and symbol names inside text.
+ *
+ * File-path pattern — matches:
+ *   - Relative paths:   `src/store/brain-schema.ts`
+ *   - Absolute paths:   `/mnt/projects/cleocode/packages/core/src/…`
+ *   - Extension-gated:  only `.ts`, `.tsx`, `.js`, `.jsx`, `.rs`, `.json`
+ *
+ * Symbol pattern — matches:
+ *   - PascalCase class/interface names: `BrainPageNodes`
+ *   - camelCase function names at word boundaries: `upsertGraphNode`
+ *   - snake_case identifiers: `brain_page_edges`
+ *
+ * Overlapping matches are deduplicated by nodeId before edge creation.
+ */
+
+const FILE_PATH_RE =
+  /(?:^|[\s`"'([\]{,])((\/[\w.\-/]+|[\w.-]+(?:\/[\w.-]+)+)\.(ts|tsx|js|jsx|rs|json))(?=$|[\s`"')[\]{,])/gm;
+
+const SYMBOL_RE =
+  /(?<![`"'/\w.])(?:[A-Z][a-zA-Z0-9]{2,}|[a-z][a-zA-Z0-9]*(?:[A-Z][a-zA-Z0-9]*)+|[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*){2,})(?![`"'/\w])/g;
+
+/**
+ * Extract file-path and symbol references from free-form text.
+ *
+ * Symbols shorter than 4 characters or matching common English stop-words
+ * are filtered to reduce noise.
+ *
+ * @param text - Decision text and/or rationale to scan.
+ * @returns Deduplicated array of extracted references.
+ */
+export function extractReferencedSymbols(text: string): ExtractedRef[] {
+  const seen = new Set<string>();
+  const refs: ExtractedRef[] = [];
+
+  // --- File paths ---
+  for (const match of text.matchAll(FILE_PATH_RE)) {
+    const raw = match[1];
+    if (!raw) continue;
+    const nodeId = `file:${raw}`;
+    if (seen.has(nodeId)) continue;
+    seen.add(nodeId);
+    refs.push({ raw, nodeId, nodeType: 'file', label: raw });
+  }
+
+  // --- Symbol names ---
+  for (const match of text.matchAll(SYMBOL_RE)) {
+    const raw = match[0];
+    if (!raw || raw.length < 4) continue;
+    if (SYMBOL_STOP_WORDS.has(raw.toLowerCase())) continue;
+    const nodeId = `symbol:${raw}`;
+    if (seen.has(nodeId)) continue;
+    seen.add(nodeId);
+    refs.push({ raw, nodeId, nodeType: 'symbol', label: raw });
+  }
+
+  return refs;
+}
+
+/**
+ * Common English / technical words that look like camelCase or PascalCase
+ * symbols but carry no meaningful code reference.  Filtered out to keep the
+ * extracted reference set signal-rich.
+ */
+const SYMBOL_STOP_WORDS = new Set([
+  'this',
+  'that',
+  'with',
+  'from',
+  'into',
+  'when',
+  'then',
+  'also',
+  'both',
+  'each',
+  'such',
+  'over',
+  'after',
+  'before',
+  'always',
+  'never',
+  'should',
+  'must',
+  'will',
+  'would',
+  'could',
+  'have',
+  'been',
+  'there',
+  'their',
+  'they',
+  'them',
+  'these',
+  'those',
+  'some',
+  'only',
+  'just',
+  'more',
+  'most',
+  'many',
+  'much',
+  'well',
+  'very',
+  'here',
+  'where',
+  'which',
+  'what',
+  'why',
+  'how',
+  'the',
+  'and',
+  'but',
+  'for',
+  'not',
+  'are',
+  'was',
+  'were',
+  'has',
+  'had',
+  'its',
+  'the',
+  'data',
+  'true',
+  'false',
+  'null',
+  'none',
+  'type',
+  'test',
+  'spec',
+  'todo',
+  'fixme',
+  'note',
+  'example',
+  'index',
+  'config',
+  'error',
+  'value',
+  'input',
+  'output',
+  'result',
+  'return',
+  'default',
+  'source',
+  'target',
+  'import',
+  'export',
+  'class',
+  'interface',
+  'function',
+  'const',
+  'async',
+  'await',
+]);
+
+// ---------------------------------------------------------------------------
+// Edge creation
+// ---------------------------------------------------------------------------
+
+/**
+ * Create `affects` edges from a decision graph node to every referenced
+ * file / symbol node.
+ *
+ * For each reference:
+ *  1. Upsert the target node (file or symbol) so the graph stays consistent.
+ *  2. Insert an `applies_to` edge from `decision:<id>` to the target node.
+ *
+ * All writes are best-effort via {@link upsertGraphNode} and
+ * {@link addGraphEdge} — failures are swallowed internally.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param decisionId  - The decision ID (e.g. `D001`).
+ * @param refs        - Extracted references returned by {@link extractReferencedSymbols}.
+ */
+export async function linkDecisionToTargets(
+  projectRoot: string,
+  decisionId: string,
+  refs: ExtractedRef[],
+): Promise<void> {
+  const fromId = `decision:${decisionId}`;
+
+  const writes = refs.map(async (ref) => {
+    // Upsert the target node so the edge has a valid destination even if the
+    // file / symbol has not been independently indexed yet.
+    await upsertGraphNode(
+      projectRoot,
+      ref.nodeId,
+      ref.nodeType,
+      ref.label,
+      0.5, // placeholder quality until nexus indexes it
+      ref.raw,
+    );
+
+    await addGraphEdge(
+      projectRoot,
+      fromId,
+      ref.nodeId,
+      'applies_to',
+      1.0,
+      'auto:decision-cross-link',
+    );
+  });
+
+  // Fire all writes concurrently — individual failures are swallowed inside
+  // upsertGraphNode / addGraphEdge.
+  await Promise.allSettled(writes);
+}
+
+// ---------------------------------------------------------------------------
+// Convenience facade
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract file/symbol references from a decision and create `applies_to`
+ * edges in the brain graph.  Combines {@link extractReferencedSymbols} and
+ * {@link linkDecisionToTargets} in one call.
+ *
+ * This is the function wired into {@link storeDecision} after a new decision
+ * is saved.  It is always fire-and-forget: the caller should NOT await it
+ * when used inside the decision write path.
+ *
+ * @param projectRoot  - Absolute path to the project root directory.
+ * @param decisionId   - The saved decision ID (e.g. `D001`).
+ * @param decisionText - Full decision text.
+ * @param rationale    - Full rationale text.
+ */
+export async function autoCrossLinkDecision(
+  projectRoot: string,
+  decisionId: string,
+  decisionText: string,
+  rationale: string,
+): Promise<void> {
+  try {
+    const combined = `${decisionText} ${rationale}`;
+    const refs = extractReferencedSymbols(combined);
+    if (refs.length === 0) return;
+    await linkDecisionToTargets(projectRoot, decisionId, refs);
+  } catch {
+    /* best-effort — never surface errors to caller */
+  }
+}

package/src/memory/decisions.ts

@@ -13,6 +13,7 @@ import { getBrainAccessor } from '../store/brain-accessor.js';
 import type { BrainDecisionRow, NewBrainDecisionRow } from '../store/brain-schema.js';
 import { taskExistsInTasksDb } from '../store/cross-db-cleanup.js';
 import { getDb } from '../store/sqlite.js';
+import { autoCrossLinkDecision } from './decision-cross-link.js';
 import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
 import { computeDecisionQuality } from './quality-scoring.js';
 import { detectSupersession, supersedeMemory } from './temporal-supersession.js';
@@ -229,6 +230,12 @@ export async function storeDecision(
         'auto:store-decision',
       );
     }
+
+    // Cross-link decision → referenced file/symbol nodes (T626 phase 1).
+    // Fire-and-forget — autoCrossLinkDecision swallows its own errors.
+    autoCrossLinkDecision(projectRoot, saved.id, saved.decision, saved.rationale).catch(() => {
+      /* best-effort */
+    });
   } catch {
     /* Graph population is best-effort — never block the primary return */
   }

package/src/memory/edge-types.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical edge-type constants for `brain_page_edges`.
+ *
+ * All code that writes or queries `brain_page_edges.edge_type` MUST use
+ * these constants instead of raw string literals to prevent enum drift.
+ *
+ * The values here are a subset of `BRAIN_EDGE_TYPES` (brain-schema.ts).
+ * They are duplicated as constants so callers do not need to import the
+ * schema module (which carries Drizzle + SQLite dependencies).
+ *
+ * @epic T626
+ */
+export const EDGE_TYPES = {
+  // Plasticity (Hebbian / STDP co-retrieval)
+  CO_RETRIEVED: 'co_retrieved',
+  // Temporal supersession
+  SUPERSEDES: 'supersedes',
+  // Task / decision / pattern → target context
+  APPLIES_TO: 'applies_to',
+  // Provenance
+  DERIVED_FROM: 'derived_from',
+  // Observation → symbol/file impact
+  AFFECTS: 'affects',
+  // Observation → symbol name mention
+  MENTIONS: 'mentions',
+  // Observation → symbol/file structural link
+  DOCUMENTS: 'documents',
+} as const;
+
+/** Discriminated union of the canonical edge type constant values. */
+export type EdgeType = (typeof EDGE_TYPES)[keyof typeof EDGE_TYPES];

package/src/memory/index.ts

@@ -1501,6 +1501,8 @@ export * from './brain-retrieval.js';
 export * from './brain-search.js';
 // === BRAIN Memory modules (brain.db backed) ===
 export * from './decisions.js';
+// === T626-M1: Canonical edge-type constants ===
+export * from './edge-types.js';
 // === T549 Wave 2: Extraction Gate ===
 export * from './extraction-gate.js';
 export * from './learnings.js';

package/src/store/brain-schema.ts

@@ -563,6 +563,8 @@ export const BRAIN_EDGE_TYPES = [
   // Graph bridging (memory ↔ code)
   'references', // observation → references → symbol
   'modified_by', // file → modified_by → session
+  // Plasticity (Hebbian + STDP co-retrieval)
+  'co_retrieved', // A → co_retrieved → B (Hebbian: frequently retrieved together)
 ] as const;
 
 /** Discriminated union of all supported brain graph edge types. */
@@ -713,6 +715,52 @@ export const brainRetrievalLog = sqliteTable(
   ],
 );
 
+// ============================================================================
+// PLASTICITY EVENTS — STDP weight-change audit log (T626 phase 5)
+// ============================================================================
+
+/**
+ * Records every STDP weight-change event applied to a brain_page_edges row.
+ *
+ * Each row captures the causal pair (source_node, target_node), the signed
+ * delta applied to the edge weight, whether it was a potentiation or
+ * depression event, and which session and timestamp triggered it.
+ *
+ * @task T626
+ * @epic T626
+ */
+export const brainPlasticityEvents = sqliteTable(
+  'brain_plasticity_events',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** from_id of the affected brain_page_edges row. */
+    sourceNode: text('source_node').notNull(),
+    /** to_id of the affected brain_page_edges row. */
+    targetNode: text('target_node').notNull(),
+    /**
+     * Signed weight delta applied to the edge.
+     * Positive = potentiation (LTP), negative = depression (LTD).
+     */
+    deltaW: real('delta_w').notNull(),
+    /**
+     * STDP event kind: `ltp` (Long-Term Potentiation) or `ltd` (Long-Term
+     * Depression).
+     */
+    kind: text('kind', { enum: ['ltp', 'ltd'] }).notNull(),
+    /** ISO 8601 timestamp when this event was applied. */
+    timestamp: text('timestamp').notNull().default(sql`(datetime('now'))`),
+    /** Session ID that triggered the STDP pass, if available. */
+    sessionId: text('session_id'),
+  },
+  (table) => [
+    index('idx_plasticity_source').on(table.sourceNode),
+    index('idx_plasticity_target').on(table.targetNode),
+    index('idx_plasticity_timestamp').on(table.timestamp),
+    index('idx_plasticity_session').on(table.sessionId),
+    index('idx_plasticity_kind').on(table.kind),
+  ],
+);
+
 // === TYPE EXPORTS ===
 
 export type BrainRetrievalLogRow = typeof brainRetrievalLog.$inferSelect;
@@ -733,4 +781,6 @@ export type BrainPageEdgeRow = typeof brainPageEdges.$inferSelect;
 export type NewBrainPageEdgeRow = typeof brainPageEdges.$inferInsert;
 export type BrainStickyNoteRow = typeof brainStickyNotes.$inferSelect;
 export type NewBrainStickyNoteRow = typeof brainStickyNotes.$inferInsert;
+export type BrainPlasticityEventRow = typeof brainPlasticityEvents.$inferSelect;
+export type NewBrainPlasticityEventRow = typeof brainPlasticityEvents.$inferInsert;
 // BrainNodeType and BrainEdgeType are declared alongside their enum arrays above.

package/src/store/brain-sqlite.ts

@@ -158,6 +158,23 @@ function runBrainMigrations(
   // all migrations as applied without actually running them (Scenario 2 race).
   // ensureColumns is idempotent — no-op if the column already exists.
   ensureColumns(nativeDb, 'brain_observations', [{ name: 'agent', ddl: 'text' }], 'brain');
+
+  // T626-M1: Normalize co_retrieved edge type — idempotent safety-net UPDATE.
+  // The shipped Hebbian strengthener emitted edge_type = 'relates_to' instead of
+  // 'co_retrieved'. Relabel only rows from the consolidation provenance so no
+  // semantic edges are affected. The Drizzle migration file does the same UPDATE;
+  // this guard handles installs where the journal reconciler already marked
+  // the migration applied before the SQL ran.
+  if (tableExists(nativeDb, 'brain_page_edges')) {
+    nativeDb
+      .prepare(
+        `UPDATE brain_page_edges
+         SET edge_type = 'co_retrieved'
+         WHERE edge_type = 'relates_to'
+           AND provenance LIKE 'consolidation:%'`,
+      )
+      .run();
+  }
 }
 
 /**