vektor-slipstream 1.2.2 → 1.3.0

package/cerebellum.js

@@ -0,0 +1,438 @@
+/**
+ * cloak_cerebellum.js
+ * Pre-write enforcer — checks every write against known error patterns in
+ * Vektor's causal graph. Auto-creates [RESOLVED_BY] edges when a fix matches
+ * an open error node. Zero extra tool calls from Claude.
+ *
+ * Two responsibilities:
+ *   1. CHECK  — before a write, recall causal error patterns and warn if matched
+ *   2. RESOLVE — if new write content matches an error pattern, auto-write
+ *                [RESOLVED_BY] causal edge to close the loop
+ *
+ * Architecture: CLOAK layer → Vektor causal graph (MAGMA §3.4)
+ * Research: MAGMA arXiv:2601.03236, OpenWolf cerebrum Do-Not-Repeat pattern
+ *
+ * Key design decision: cerebellum NEVER blocks a write, it only warns.
+ * Claude Code must remain in control — cerebellum is advisory, not a gatekeeper.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+// ---------------------------------------------------------------------------
+// Similarity threshold for pattern matching
+// ---------------------------------------------------------------------------
+const SIMILARITY_THRESHOLD = 0.72;
+
+// Max error patterns to check per write
+const MAX_PATTERNS_TO_CHECK = 8;
+
+// Minimum content length to bother checking — skip tiny edits (console.log,
+// closing braces, single-line comments). Not worth a Vektor round-trip.
+const MIN_CHECK_LENGTH = 50;
+
+// ---------------------------------------------------------------------------
+// LRU warning cache — prevents slamming Vektor on rapid multi-file writes
+// (MultiEdit, code generation loops, etc.)
+//
+// Key:   SHA-1 of content.slice(0,300) — cheap, collision-safe for this use
+// Value: { warnings, cachedAt }
+// TTL:   60 seconds — patterns don't change that fast within a session
+// Max:   100 entries — bounded memory, evicts oldest on overflow
+// ---------------------------------------------------------------------------
+const CACHE_TTL_MS  = 60_000;
+const CACHE_MAX     = 100;
+const _warningCache = new Map(); // key → { warnings, cachedAt }
+
+function _cacheKey(content) {
+  return crypto.createHash('sha1').update(content.slice(0, 300)).digest('hex');
+}
+
+function _cacheGet(key) {
+  const entry = _warningCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.cachedAt > CACHE_TTL_MS) {
+    _warningCache.delete(key);
+    return null;
+  }
+  return entry.warnings;
+}
+
+function _cacheSet(key, warnings) {
+  // Evict oldest entry if at capacity
+  if (_warningCache.size >= CACHE_MAX) {
+    _warningCache.delete(_warningCache.keys().next().value);
+  }
+  _warningCache.set(key, { warnings, cachedAt: Date.now() });
+}
+
+// ---------------------------------------------------------------------------
+// Pattern storage key prefix — namespaces cerebellum nodes in Vektor
+// ---------------------------------------------------------------------------
+const ERROR_PREFIX    = '[CLOAK_CEREBELLUM_ERROR]';
+const RESOLVED_PREFIX = '[CLOAK_CEREBELLUM_RESOLVED]';
+const DNR_PREFIX      = '[CLOAK_CEREBELLUM_DNR]';  // Do-Not-Repeat
+
+// ---------------------------------------------------------------------------
+// Core: check a write against known error patterns
+// ---------------------------------------------------------------------------
+
+/**
+ * checkWrite({ content, filePath, memory })
+ * Called from the PreToolUse hook before every write.
+ * Returns warnings if the write matches known error patterns.
+ *
+ * @param {string} content   - The content being written
+ * @param {string} filePath  - The file being written to
+ * @param {object} memory    - Vektor memory instance
+ * @returns {object}         - { warnings: [], shouldProceed: true }
+ */
+async function checkWrite({ content, filePath, memory } = {}) {
+  if (!memory)  throw new Error('cloak_cerebellum: memory instance is required');
+  if (!content) return { warnings: [], shouldProceed: true, cached: false };
+
+  // Bypass: tiny writes aren't worth a Vektor round-trip
+  // (closing braces, console.logs, single-line cosmetic edits)
+  if (content.length < MIN_CHECK_LENGTH) {
+    return { warnings: [], shouldProceed: true, bypassed: 'too_small' };
+  }
+
+  // Cache hit: same content checked recently — return instantly, no Vektor call
+  const key    = _cacheKey(content);
+  const cached = _cacheGet(key);
+  if (cached !== null) {
+    return {
+      warnings    : cached,
+      shouldProceed: true,
+      hasBlockers : cached.some(w => w.severity === 'block'),
+      cached      : true,
+    };
+  }
+
+  const warnings = [];
+
+  try {
+    // Query causal error graph for patterns similar to this write
+    const errorPatterns = await memory.recall(
+      `${ERROR_PREFIX} ${content.slice(0, 300)}`,
+      { limit: MAX_PATTERNS_TO_CHECK }
+    );
+
+    if (!errorPatterns || errorPatterns.length === 0) {
+      return { warnings: [], shouldProceed: true };
+    }
+
+    for (const pattern of errorPatterns) {
+      if (pattern.score < SIMILARITY_THRESHOLD) continue;
+
+      // Parse the stored pattern
+      const parsed = parsePatternNode(pattern.content);
+      if (!parsed) continue;
+
+      // Skip if this pattern is already resolved
+      if (parsed.resolvedBy) continue;
+
+      warnings.push({
+        patternId   : pattern.id,
+        description : parsed.description,
+        originalFile: parsed.file,
+        severity    : parsed.severity || 'warn',
+        hint        : parsed.fix || 'See error pattern for details',
+        score       : Math.round(pattern.score * 100) / 100,
+      });
+    }
+
+    // Also check Do-Not-Repeat rules (always enforced regardless of similarity)
+    const dnrRules = await memory.recall(
+      `${DNR_PREFIX}`,
+      { limit: 5 }
+    );
+
+    if (dnrRules) {
+      for (const rule of dnrRules) {
+        const parsed = parseDNRNode(rule.content);
+        if (!parsed) continue;
+
+        // Check if the pattern keyword appears in the write content
+        if (content.toLowerCase().includes(parsed.keyword.toLowerCase())) {
+          warnings.push({
+            patternId   : rule.id,
+            description : `Do-Not-Repeat: ${parsed.rule}`,
+            severity    : 'block',
+            hint        : parsed.alternative || 'Avoid this pattern',
+            score       : 1.0,
+          });
+        }
+      }
+    }
+
+  } catch (err) {
+    // Non-fatal — Vektor query failure should not block writes
+    console.warn('[cloak_cerebellum] Pattern check failed:', err.message);
+  }
+
+  // Cache the result for 60s — rapid multi-file writes skip Vektor entirely
+  _cacheSet(key, warnings);
+
+  return {
+    warnings,
+    shouldProceed: true,
+    hasBlockers  : warnings.some(w => w.severity === 'block'),
+    cached       : false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Core: record a new error pattern into the causal graph
+// ---------------------------------------------------------------------------
+
+/**
+ * recordError({ description, filePath, errorType, fix, severity, memory })
+ * Store a new error pattern so future writes can be warned.
+ *
+ * @param {string} description  - Human-readable description of the error
+ * @param {string} filePath     - File where error occurred
+ * @param {string} errorType    - e.g. 'null_reference', 'type_mismatch'
+ * @param {string} fix          - What fixed it (optional)
+ * @param {'warn'|'block'} severity
+ * @param {object} memory       - Vektor memory instance
+ * @returns {object}            - { id, written }
+ */
+async function recordError({ description, filePath, errorType, fix, severity = 'warn', memory } = {}) {
+  if (!memory)      throw new Error('cloak_cerebellum: memory instance is required');
+  if (!description) throw new Error('cloak_cerebellum: description is required');
+
+  const patternStr = [
+    ERROR_PREFIX,
+    `error_type:${errorType || 'unknown'}`,
+    `file:${filePath || 'unknown'}`,
+    `description:${description}`,
+    `severity:${severity}`,
+    fix ? `fix:${fix}` : null,
+    `recorded_at:${new Date().toISOString()}`,
+    `resolved:false`,
+  ].filter(Boolean).join(' | ');
+
+  try {
+    await memory.remember(patternStr);
+    return { written: true, pattern: patternStr };
+  } catch (err) {
+    console.error('[cloak_cerebellum] Failed to record error:', err.message);
+    return { written: false, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core: auto-resolve — detect when a write fixes an open error
+// Called from PostToolUse after a successful write.
+// This is the key improvement over OpenWolf — resolution is automatic,
+// not dependent on Claude remembering to call a separate tool.
+// ---------------------------------------------------------------------------
+
+/**
+ * autoResolve({ content, filePath, memory })
+ * After a successful write, check if it resolves any open error patterns.
+ * If yes, write a [RESOLVED_BY] causal edge to close the loop.
+ * This feeds the decay weighting in MAGMA's causal graph.
+ *
+ * @param {string} content   - Content that was written
+ * @param {string} filePath  - File that was written
+ * @param {object} memory    - Vektor memory instance
+ * @returns {object}         - { resolved: [], written: number }
+ */
+async function autoResolve({ content, filePath, memory } = {}) {
+  if (!memory || !filePath) return { resolved: [], written: 0 };
+
+  const resolved = [];
+
+  try {
+    // Query by FILE PATH not content — avoids the semantic gap where
+    // "Null reference on user.id" and "if (user && user.id)" have
+    // completely different embeddings despite one fixing the other.
+    // Pull all open errors on this file, then let REM cycle verify.
+    const candidates = await memory.recall(
+      `${ERROR_PREFIX} file:${filePath}`,
+      { limit: MAX_PATTERNS_TO_CHECK }
+    );
+
+    if (!candidates || candidates.length === 0) return { resolved: [], written: 0 };
+
+    for (const candidate of candidates) {
+      // File path match is already a strong signal — use lower threshold
+      // than content matching. 0.5 avoids completely unrelated file path
+      // substring matches while catching real file-based errors.
+      if (candidate.score < 0.5) continue;
+
+      const parsed = parsePatternNode(candidate.content);
+      if (!parsed || parsed.resolvedBy) continue; // already resolved
+
+      // Only auto-resolve if the stored error references this exact file
+      if (parsed.file && parsed.file !== filePath &&
+          parsed.file !== require('path').basename(filePath)) continue;
+
+      // Write resolution node — this is the [RESOLVED_BY] causal edge
+      const resolutionStr = [
+        RESOLVED_PREFIX,
+        `resolves_pattern:${candidate.id}`,
+        `original_error:${parsed.description}`,
+        `resolved_by_file:${filePath || 'unknown'}`,
+        `resolved_at:${new Date().toISOString()}`,
+        `[RESOLVED_BY]`, // explicit causal edge marker for HippoRAG decay weighting
+      ].join(' | ');
+
+      try {
+        await memory.remember(resolutionStr);
+        resolved.push({
+          patternId  : candidate.id,
+          description: parsed.description,
+          resolution : resolutionStr,
+        });
+      } catch (err) {
+        console.warn('[cloak_cerebellum] Failed to write resolution:', err.message);
+      }
+    }
+
+  } catch (err) {
+    console.warn('[cloak_cerebellum] Auto-resolve query failed:', err.message);
+  }
+
+  return { resolved, written: resolved.length };
+}
+
+// ---------------------------------------------------------------------------
+// Do-Not-Repeat rules — project-level conventions
+// ---------------------------------------------------------------------------
+
+/**
+ * addDNRRule({ keyword, rule, alternative, memory })
+ * Store a Do-Not-Repeat rule. Checked on every write regardless of similarity.
+ *
+ * @param {string} keyword     - Trigger keyword/pattern to watch for
+ * @param {string} rule        - Human description of what not to do
+ * @param {string} alternative - What to do instead
+ * @param {object} memory
+ */
+async function addDNRRule({ keyword, rule, alternative, memory } = {}) {
+  if (!memory)  throw new Error('cloak_cerebellum: memory instance is required');
+  if (!keyword) throw new Error('cloak_cerebellum: keyword is required');
+  if (!rule)    throw new Error('cloak_cerebellum: rule is required');
+
+  const dnrStr = [
+    DNR_PREFIX,
+    `keyword:${keyword}`,
+    `rule:${rule}`,
+    alternative ? `alternative:${alternative}` : null,
+    `added_at:${new Date().toISOString()}`,
+  ].filter(Boolean).join(' | ');
+
+  try {
+    await memory.remember(dnrStr);
+    return { written: true };
+  } catch (err) {
+    console.error('[cloak_cerebellum] Failed to add DNR rule:', err.message);
+    return { written: false, error: err.message };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code hook integration
+// ---------------------------------------------------------------------------
+
+/**
+ * handleHookPayload({ payload, memory })
+ * Routes Claude Code PreToolUse/PostToolUse hooks to checkWrite / autoResolve.
+ */
+async function handleHookPayload({ payload, memory } = {}) {
+  if (!memory || !payload) return null;
+
+  const hookName = payload?.hook_event_name || payload?.event;
+  const tool     = payload?.tool_name;
+  const input    = payload?.tool_input;
+  const output   = payload?.tool_response;
+
+  const isWrite = ['Write', 'Edit', 'MultiEdit', 'Bash'].includes(tool);
+
+  switch (hookName) {
+    case 'PreToolUse':
+    case 'pre_tool_use': {
+      if (!isWrite) return null;
+
+      // Bug fix: MultiEdit sends input.edits = [{ old_string, new_string }]
+      // not a flat input.new_string. Concatenate all new_string blocks so
+      // cerebellum actually sees the content being written in refactors.
+      let content = input?.new_string || input?.content || input?.command || '';
+      if (!content && input?.edits && Array.isArray(input.edits)) {
+        content = input.edits.map(e => e.new_string || '').filter(Boolean).join('\n');
+      }
+
+      const filePath = input?.file_path || input?.path || '';
+      return checkWrite({ content, filePath, memory });
+    }
+
+    case 'PostToolUse':
+    case 'post_tool_use': {
+      if (!isWrite) return null;
+      const success = !output?.error;
+      if (!success) return null;
+
+      // Same MultiEdit fix on the post-write resolve path
+      let content = input?.new_string || input?.content || '';
+      if (!content && input?.edits && Array.isArray(input.edits)) {
+        content = input.edits.map(e => e.new_string || '').filter(Boolean).join('\n');
+      }
+
+      const filePath = input?.file_path || input?.path || '';
+      return autoResolve({ content, filePath, memory });
+    }
+
+    default:
+      return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parsers — extract structured data from Vektor node strings
+// ---------------------------------------------------------------------------
+function parsePatternNode(str) {
+  if (!str || !str.includes(ERROR_PREFIX)) return null;
+  const parts = str.split(' | ');
+  const get   = key => {
+    const part = parts.find(p => p.startsWith(`${key}:`));
+    return part ? part.slice(key.length + 1) : null;
+  };
+  return {
+    errorType : get('error_type'),
+    file      : get('file'),
+    description: get('description'),
+    severity  : get('severity'),
+    fix       : get('fix'),
+    resolvedBy: str.includes(RESOLVED_PREFIX) || get('resolved') === 'true' ? true : null,
+  };
+}
+
+function parseDNRNode(str) {
+  if (!str || !str.includes(DNR_PREFIX)) return null;
+  const parts = str.split(' | ');
+  const get   = key => {
+    const part = parts.find(p => p.startsWith(`${key}:`));
+    return part ? part.slice(key.length + 1) : null;
+  };
+  return {
+    keyword    : get('keyword'),
+    rule       : get('rule'),
+    alternative: get('alternative'),
+  };
+}
+
+module.exports = {
+  checkWrite,
+  recordError,
+  autoResolve,
+  addDNRRule,
+  handleHookPayload,
+  SIMILARITY_THRESHOLD,
+  ERROR_PREFIX,
+  RESOLVED_PREFIX,
+  DNR_PREFIX,
+};

package/cortex.js

@@ -0,0 +1,221 @@
+/**
+ * cloak_cortex.js
+ * File anatomy scanner — builds a token-aware project index in Vektor's entity graph.
+ * Called once on init, then on significant file changes (not per-session).
+ *
+ * Writes to Vektor as entity nodes:
+ *   "file:src/server.ts | purpose: Express HTTP server | tokens: ~520 | last_scanned: <iso>"
+ *
+ * Architecture: CLOAK layer → Vektor entity graph (MAGMA §3.2)
+ * Research: MAGMA arXiv:2601.03236, OpenWolf anatomy pattern
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Token estimation (OpenWolf ratios — accurate to ±15%)
+// ---------------------------------------------------------------------------
+const TOKEN_RATIOS = {
+  code : 3.5,   // .js .ts .py .go .rs etc.
+  prose: 4.0,   // .md .txt .rst
+  mixed: 3.75,  // .json .yaml .toml .html
+};
+
+const CODE_EXTS  = new Set(['.js','.ts','.jsx','.tsx','.py','.go','.rs','.rb','.java','.c','.cpp','.cs','.php','.swift','.kt']);
+const PROSE_EXTS = new Set(['.md','.txt','.rst','.mdx']);
+const SKIP_DIRS  = new Set(['node_modules','.git','dist','build','.next','__pycache__','.cache','coverage','.wolf']);
+const SKIP_FILES = new Set(['.DS_Store','package-lock.json','yarn.lock','pnpm-lock.yaml']);
+
+function estimateTokens(filePath, bytes) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (CODE_EXTS.has(ext))  return Math.round(bytes / TOKEN_RATIOS.code);
+  if (PROSE_EXTS.has(ext)) return Math.round(bytes / TOKEN_RATIOS.prose);
+  return Math.round(bytes / TOKEN_RATIOS.mixed);
+}
+
+// ---------------------------------------------------------------------------
+// File scanner
+// ---------------------------------------------------------------------------
+function scanDirectory(dirPath, results = [], rootPath = dirPath, visited = new Set()) {
+  // Only resolve realpath for symlinks — not for every directory.
+  // Running fs.realpathSync on all directories is ~4x slower on large codebases
+  // (especially Windows NTFS) and the visited Set grows unnecessarily large.
+  // Normal directories cannot create cycles; only symlinks can.
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (SKIP_FILES.has(entry.name)) continue;
+
+    const fullPath = path.join(dirPath, entry.name);
+    const relPath  = path.relative(rootPath, fullPath);
+
+    if (entry.isSymbolicLink()) {
+      // Symlinks only: resolve real path and check for cycles
+      let realPath;
+      try { realPath = fs.realpathSync(fullPath); } catch { continue; }
+
+      if (visited.has(realPath)) continue; // cycle detected — skip
+
+      let stat;
+      try { stat = fs.statSync(fullPath); } catch { continue; }
+
+      if (stat.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          visited.add(realPath); // mark before recursing
+          scanDirectory(fullPath, results, rootPath, visited);
+        }
+      } else if (stat.isFile()) {
+        const ext    = path.extname(entry.name).toLowerCase();
+        const tokens = estimateTokens(fullPath, stat.size);
+        results.push({ relPath, ext, tokens, mtime: stat.mtimeMs, bytes: stat.size });
+      }
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      // Normal directory — no realpathSync needed, no cycle possible
+      if (!SKIP_DIRS.has(entry.name)) {
+        scanDirectory(fullPath, results, rootPath, visited);
+      }
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+
+    let stat;
+    try { stat = fs.statSync(fullPath); } catch { continue; }
+
+    const ext    = path.extname(entry.name).toLowerCase();
+    const tokens = estimateTokens(fullPath, stat.size);
+    const mtime  = stat.mtimeMs;
+
+    results.push({ relPath, ext, tokens, mtime, bytes: stat.size });
+  }
+
+  return results;
+}
+
+// isSymlinkDir removed — logic inlined above for clarity
+
+// ---------------------------------------------------------------------------
+// Build Vektor memory strings for entity graph
+// ---------------------------------------------------------------------------
+function buildEntityString(file, projectName) {
+  return [
+    `[CLOAK_CORTEX] project:${projectName}`,
+    `file:${file.relPath}`,
+    `tokens:~${file.tokens}`,
+    `size:${file.bytes}b`,
+    `last_modified:${new Date(file.mtime).toISOString()}`,
+  ].join(' | ');
+}
+
+// ---------------------------------------------------------------------------
+// Load/save scan cache (.wolf/cortex-cache.json) to avoid rescanning unchanged files
+// ---------------------------------------------------------------------------
+function loadCache(projectPath) {
+  const cachePath = path.join(projectPath, '.wolf', 'cortex-cache.json');
+  try {
+    return JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveCache(projectPath, cache) {
+  const wolfDir = path.join(projectPath, '.wolf');
+  if (!fs.existsSync(wolfDir)) fs.mkdirSync(wolfDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(wolfDir, 'cortex-cache.json'),
+    JSON.stringify(cache, null, 2)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * runCortex({ projectPath, memory, force })
+ *
+ * @param {string}  projectPath  - Absolute path to project root
+ * @param {object}  memory       - Vektor memory instance (vektor-slipstream)
+ * @param {boolean} force        - Re-scan all files even if unchanged
+ * @returns {object}             - { scanned, skipped, written, totalTokens, anatomy }
+ */
+async function runCortex({ projectPath, memory, force = false } = {}) {
+  if (!projectPath) throw new Error('cloak_cortex: projectPath is required');
+  if (!memory)      throw new Error('cloak_cortex: memory instance is required');
+
+  const projectName = path.basename(projectPath);
+  const cache       = force ? {} : loadCache(projectPath);
+  const files       = scanDirectory(projectPath);
+
+  const stats = { scanned: 0, skipped: 0, written: 0, totalTokens: 0 };
+  const anatomy = [];
+
+  for (const file of files) {
+    stats.totalTokens += file.tokens;
+    anatomy.push({ path: file.relPath, tokens: file.tokens });
+
+    // Skip if file hasn't changed since last scan
+    const cacheKey = file.relPath;
+    if (!force && cache[cacheKey] && cache[cacheKey].mtime === file.mtime) {
+      stats.skipped++;
+      continue;
+    }
+
+    stats.scanned++;
+
+    const entityStr = buildEntityString(file, projectName);
+
+    try {
+      await memory.remember(entityStr);
+      cache[cacheKey] = { mtime: file.mtime, tokens: file.tokens };
+      stats.written++;
+    } catch (err) {
+      console.error(`[cloak_cortex] Failed to write entity for ${file.relPath}:`, err.message);
+    }
+  }
+
+  // Write project-level summary node
+  const summaryStr = [
+    `[CLOAK_CORTEX_SUMMARY] project:${projectName}`,
+    `total_files:${files.length}`,
+    `total_tokens:~${stats.totalTokens}`,
+    `scanned_at:${new Date().toISOString()}`,
+  ].join(' | ');
+
+  try {
+    await memory.remember(summaryStr);
+  } catch (err) {
+    console.error('[cloak_cortex] Failed to write summary node:', err.message);
+  }
+
+  saveCache(projectPath, cache);
+
+  return { ...stats, anatomy };
+}
+
+/**
+ * getAnatomy({ projectPath })
+ * Returns the cached anatomy without hitting Vektor — for fast pre-read hints.
+ */
+function getAnatomy(projectPath) {
+  const cache = loadCache(projectPath);
+  return Object.entries(cache).map(([relPath, data]) => ({
+    path: relPath,
+    tokens: data.tokens,
+  })).sort((a, b) => b.tokens - a.tokens);
+}
+
+module.exports = { runCortex, getAnatomy, scanDirectory, estimateTokens };