total-recall-brain 3.3.0 → 3.4.0

package/src/server/route-manifest.json

@@ -1,79 +1,346 @@
 [
-  { "method": "GET", "path": "/api/memory" },
-  { "method": "GET", "path": "/api/memory/stats" },
-  { "method": "GET", "path": "/api/memory/:slug" },
-  { "method": "POST", "path": "/api/memory" },
-  { "method": "PUT", "path": "/api/memory/:slug" },
-  { "method": "PATCH", "path": "/api/memory/:slug" },
-  { "method": "DELETE", "path": "/api/memory/:slug" },
-  { "method": "GET", "path": "/api/keys" },
-  { "method": "POST", "path": "/api/keys" },
-  { "method": "DELETE", "path": "/api/keys/:id" },
-  { "method": "GET", "path": "/api/sessions" },
-  { "method": "GET", "path": "/api/sessions/:id" },
-  { "method": "POST", "path": "/api/sessions/ingest" },
-  { "method": "DELETE", "path": "/api/sessions/:id" },
-  { "method": "POST", "path": "/api/memory/search/semantic" },
-  { "method": "POST", "path": "/api/vault/compile" },
-  { "method": "POST", "path": "/api/dream" },
-  { "method": "GET", "path": "/api/vault/status" },
-  { "method": "POST", "path": "/api/sandbox" },
-  { "method": "GET", "path": "/api/config" },
-  { "method": "GET", "path": "/v1/models" },
-  { "method": "GET", "path": "/.well-known/total-recall.json" },
-  { "method": "GET", "path": "/api" },
-  { "method": "GET", "path": "/api/research" },
-  { "method": "POST", "path": "/api/research" },
-  { "method": "PATCH", "path": "/api/research/:id" },
-  { "method": "DELETE", "path": "/api/research/:id" },
-  { "method": "GET", "path": "/api/integrations/active" },
-  { "method": "POST", "path": "/api/integrations/connect" },
-  { "method": "GET", "path": "/api/import/rules" },
-  { "method": "POST", "path": "/api/import/rules" },
-  { "method": "GET", "path": "/api/brain/export" },
-  { "method": "GET", "path": "/api/graph" },
-  { "method": "GET", "path": "/api/conflicts" },
-  { "method": "POST", "path": "/api/conflicts/resolve" },
-  { "method": "GET", "path": "/api/files" },
-  { "method": "GET", "path": "/api/skills" },
-  { "method": "GET", "path": "/api/skills/search" },
-  { "method": "POST", "path": "/api/skills/install" },
-  { "method": "GET", "path": "/api/skills/:name" },
-  { "method": "PUT", "path": "/api/skills/:name" },
-  { "method": "DELETE", "path": "/api/skills/:name" },
-  { "method": "GET", "path": "/api/logs/:type" },
-  { "method": "GET", "path": "/api/tasks" },
-  { "method": "POST", "path": "/api/tasks" },
-  { "method": "GET", "path": "/api/config-json" },
-  { "method": "POST", "path": "/api/config-json" },
-  { "method": "GET", "path": "/api/usage" },
-  { "method": "GET", "path": "/api/config/:name" },
-  { "method": "PUT", "path": "/api/config/:name" },
-  { "method": "POST", "path": "/api/capture/:source" },
-  { "method": "POST", "path": "/auth/login" },
-  { "method": "POST", "path": "/auth/logout" },
-  { "method": "POST", "path": "/auth/change-password" },
-  { "method": "GET", "path": "/auth/me" },
-  { "method": "GET", "path": "/auth/status" },
-  { "method": "POST", "path": "/auth/setup" },
-  { "method": "GET", "path": "/api/tts/status" },
-  { "method": "POST", "path": "/api/tts" },
-  { "method": "GET", "path": "/api/instructions" },
-  { "method": "PUT", "path": "/api/instructions" },
-  { "method": "GET", "path": "/api/ssss" },
-  { "method": "GET", "path": "/api/ssss/instructions" },
-  { "method": "GET", "path": "/api/ssss/skill/ssss" },
-  { "method": "GET", "path": "/api/ssss/spec" },
-  { "method": "GET", "path": "/api/ssss/references" },
-  { "method": "GET", "path": "/api/ssss/references/:name" },
-  { "method": "GET", "path": "/api/scripts" },
-  { "method": "GET", "path": "/api/scripts/:name" },
-  { "method": "PUT", "path": "/api/scripts/:name" },
-  { "method": "POST", "path": "/api/scripts/:name/run" },
-  { "method": "GET", "path": "/api/brains" },
-  { "method": "GET", "path": "/api/brains/:id/nodes" },
-  { "method": "GET", "path": "/api/gemini-models" },
-  { "method": "POST", "path": "/api/share" },
-  { "method": "GET", "path": "/api/extension/download" },
-  { "method": "GET", "path": "/api/extension/status" }
+  {
+    "method": "GET",
+    "path": "/.well-known/total-recall.json"
+  },
+  {
+    "method": "GET",
+    "path": "/api"
+  },
+  {
+    "method": "GET",
+    "path": "/api/brain/export"
+  },
+  {
+    "method": "GET",
+    "path": "/api/brains"
+  },
+  {
+    "method": "GET",
+    "path": "/api/brains/:id/nodes"
+  },
+  {
+    "method": "POST",
+    "path": "/api/capture/:source"
+  },
+  {
+    "method": "GET",
+    "path": "/api/config"
+  },
+  {
+    "method": "GET",
+    "path": "/api/config-json"
+  },
+  {
+    "method": "POST",
+    "path": "/api/config-json"
+  },
+  {
+    "method": "GET",
+    "path": "/api/config/:name"
+  },
+  {
+    "method": "PUT",
+    "path": "/api/config/:name"
+  },
+  {
+    "method": "GET",
+    "path": "/api/conflicts"
+  },
+  {
+    "method": "POST",
+    "path": "/api/conflicts/resolve"
+  },
+  {
+    "method": "POST",
+    "path": "/api/context"
+  },
+  {
+    "method": "GET",
+    "path": "/api/context/flash/health"
+  },
+  {
+    "method": "GET",
+    "path": "/api/context/preview"
+  },
+  {
+    "method": "POST",
+    "path": "/api/context/stream"
+  },
+  {
+    "method": "POST",
+    "path": "/api/dream"
+  },
+  {
+    "method": "GET",
+    "path": "/api/extension/download"
+  },
+  {
+    "method": "GET",
+    "path": "/api/extension/status"
+  },
+  {
+    "method": "POST",
+    "path": "/api/field/compile"
+  },
+  {
+    "method": "POST",
+    "path": "/api/field/sample"
+  },
+  {
+    "method": "GET",
+    "path": "/api/field/stats"
+  },
+  {
+    "method": "GET",
+    "path": "/api/files"
+  },
+  {
+    "method": "GET",
+    "path": "/api/gemini-models"
+  },
+  {
+    "method": "GET",
+    "path": "/api/graph"
+  },
+  {
+    "method": "GET",
+    "path": "/api/import/rules"
+  },
+  {
+    "method": "POST",
+    "path": "/api/import/rules"
+  },
+  {
+    "method": "GET",
+    "path": "/api/instructions"
+  },
+  {
+    "method": "PUT",
+    "path": "/api/instructions"
+  },
+  {
+    "method": "GET",
+    "path": "/api/integrations/active"
+  },
+  {
+    "method": "POST",
+    "path": "/api/integrations/connect"
+  },
+  {
+    "method": "GET",
+    "path": "/api/keys"
+  },
+  {
+    "method": "POST",
+    "path": "/api/keys"
+  },
+  {
+    "method": "DELETE",
+    "path": "/api/keys/:id"
+  },
+  {
+    "method": "GET",
+    "path": "/api/logs/:type"
+  },
+  {
+    "method": "GET",
+    "path": "/api/memory"
+  },
+  {
+    "method": "POST",
+    "path": "/api/memory"
+  },
+  {
+    "method": "DELETE",
+    "path": "/api/memory/:slug"
+  },
+  {
+    "method": "GET",
+    "path": "/api/memory/:slug"
+  },
+  {
+    "method": "PATCH",
+    "path": "/api/memory/:slug"
+  },
+  {
+    "method": "PUT",
+    "path": "/api/memory/:slug"
+  },
+  {
+    "method": "POST",
+    "path": "/api/memory/search/semantic"
+  },
+  {
+    "method": "GET",
+    "path": "/api/memory/stats"
+  },
+  {
+    "method": "GET",
+    "path": "/api/research"
+  },
+  {
+    "method": "POST",
+    "path": "/api/research"
+  },
+  {
+    "method": "DELETE",
+    "path": "/api/research/:id"
+  },
+  {
+    "method": "PATCH",
+    "path": "/api/research/:id"
+  },
+  {
+    "method": "POST",
+    "path": "/api/sandbox"
+  },
+  {
+    "method": "GET",
+    "path": "/api/scripts"
+  },
+  {
+    "method": "GET",
+    "path": "/api/scripts/:name"
+  },
+  {
+    "method": "PUT",
+    "path": "/api/scripts/:name"
+  },
+  {
+    "method": "POST",
+    "path": "/api/scripts/:name/run"
+  },
+  {
+    "method": "GET",
+    "path": "/api/sessions"
+  },
+  {
+    "method": "DELETE",
+    "path": "/api/sessions/:id"
+  },
+  {
+    "method": "GET",
+    "path": "/api/sessions/:id"
+  },
+  {
+    "method": "POST",
+    "path": "/api/sessions/ingest"
+  },
+  {
+    "method": "POST",
+    "path": "/api/share"
+  },
+  {
+    "method": "GET",
+    "path": "/api/skills"
+  },
+  {
+    "method": "DELETE",
+    "path": "/api/skills/:name"
+  },
+  {
+    "method": "GET",
+    "path": "/api/skills/:name"
+  },
+  {
+    "method": "PUT",
+    "path": "/api/skills/:name"
+  },
+  {
+    "method": "POST",
+    "path": "/api/skills/install"
+  },
+  {
+    "method": "GET",
+    "path": "/api/skills/search"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss/instructions"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss/references"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss/references/:name"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss/skill/ssss"
+  },
+  {
+    "method": "GET",
+    "path": "/api/ssss/spec"
+  },
+  {
+    "method": "GET",
+    "path": "/api/tasks"
+  },
+  {
+    "method": "POST",
+    "path": "/api/tasks"
+  },
+  {
+    "method": "POST",
+    "path": "/api/tts"
+  },
+  {
+    "method": "GET",
+    "path": "/api/tts/status"
+  },
+  {
+    "method": "GET",
+    "path": "/api/usage"
+  },
+  {
+    "method": "POST",
+    "path": "/api/vault/compact"
+  },
+  {
+    "method": "POST",
+    "path": "/api/vault/compile"
+  },
+  {
+    "method": "GET",
+    "path": "/api/vault/hash"
+  },
+  {
+    "method": "GET",
+    "path": "/api/vault/status"
+  },
+  {
+    "method": "POST",
+    "path": "/auth/change-password"
+  },
+  {
+    "method": "POST",
+    "path": "/auth/login"
+  },
+  {
+    "method": "POST",
+    "path": "/auth/logout"
+  },
+  {
+    "method": "GET",
+    "path": "/auth/me"
+  },
+  {
+    "method": "POST",
+    "path": "/auth/setup"
+  },
+  {
+    "method": "GET",
+    "path": "/auth/status"
+  },
+  {
+    "method": "GET",
+    "path": "/v1/models"
+  }
 ]

package/src/server/routes/memory.mjs

@@ -13,7 +13,8 @@
 import express from 'express';
 import fs from 'node:fs';
 import path from 'node:path';
-import { writeNode, createMemoryNode, walkMd } from '../../core/vault.mjs';
+import { createMemoryNode, walkMd } from '../../core/vault.mjs';
+import { writeNodeValidated } from '../../core/validated-write.mjs';
 import { getNodes, invalidate } from '../../core/vault-cache.mjs';
 import { requireAuth, requireScope } from '../auth.mjs';
 import { compileSurface } from '../../core/surface.mjs';
@@ -35,6 +36,10 @@ import {
 
 const router = express.Router();
 
+/* ── OPT-6: debounce recompilation across rapid consecutive writes ── */
+let recompileTimer = null;
+const RECOMPILE_DEBOUNCE_MS = 2000; // 2-second quiet period
+
 function nodes(vaultDir = VAULT_DIR) {
   return getNodes(vaultDir);
 }
@@ -44,51 +49,70 @@ function nodes(vaultDir = VAULT_DIR) {
  * Auto-mutates the brain in real time when any fact is written, updated, or deleted!
  */
 async function triggerMutation(node, vaultDir = VAULT_DIR) {
+  // 1. Semantic conflict detection runs IMMEDIATELY (lightweight, per-node)
   try {
-    // 1. Semantic conflict detection & auto-resolution (Sovereign OS Intelligence)
-    try {
-      const existing = nodes(vaultDir);
-      if (node && node.type === 'memory') {
-        detectAndResolve(node, existing, {
-          vaultDir,
-          inboxDir: path.join(BRAIN_DIR, 'memory-inbox'),
-        });
-      }
-    } catch (conflictErr) {
-      // Non-fatal fallback
+    const existing = nodes(vaultDir);
+    if (node && node.type === 'memory') {
+      detectAndResolve(node, existing, {
+        vaultDir,
+        inboxDir: path.join(BRAIN_DIR, 'memory-inbox'),
+      });
     }
+  } catch (conflictErr) {
+    // Non-fatal fallback
+  }
 
-    // 2. Recompile instructions surface
-    await compileSurface({
-      vaultDir,
-      skillsDir:       SKILLS_DIR,
-      derivedDir:      DERIVED_DIR,
-      instructionsFile: INSTRUCTIONS,
-    });
-
-    // 3. Rebuild dense embeddings index incrementally in background
+  // 2+3. Debounce the EXPENSIVE recompile + embeddings rebuild.
+  //       Rapid consecutive writes accumulate; only ONE compile fires
+  //       after a quiet period. Vault-cache is already invalidated
+  //       immediately at each call-site via invalidate().
+  if (recompileTimer) clearTimeout(recompileTimer);
+  recompileTimer = setTimeout(async () => {
+    recompileTimer = null;
     try {
-      const vaultNodes = nodes(vaultDir);
-      await buildEmbeddingsIndex(vaultNodes, DERIVED_DIR);
-      await buildSessionEmbeddingsIndex(SESSIONS_DIR, DERIVED_DIR);
-    } catch (embedErr) {
-      // Ollama/embeddings offline non-fatal
+      // Recompile instructions surface
+      await compileSurface({
+        vaultDir,
+        skillsDir:       SKILLS_DIR,
+        derivedDir:      DERIVED_DIR,
+        instructionsFile: INSTRUCTIONS,
+      });
+
+      // Rebuild dense embeddings index
+      try {
+        const vaultNodes = nodes(vaultDir);
+        await buildEmbeddingsIndex(vaultNodes, DERIVED_DIR);
+        await buildSessionEmbeddingsIndex(SESSIONS_DIR, DERIVED_DIR);
+      } catch (embedErr) {
+        // Ollama/embeddings offline non-fatal
+      }
+    } catch (err) {
+      // Non-fatal background log
     }
-  } catch (err) {
-    // Non-fatal background log
-  }
+  }, RECOMPILE_DEBOUNCE_MS);
 }
 
 
 // SSSS v2 frontmatter fields we pass through verbatim from request bodies.
-const PASSTHROUGH_FIELDS = ['priority', 'modality', 'confidence', 'importance', 'status', 'related', 'sources'];
+const PASSTHROUGH_FIELDS = [
+  'priority',
+  'modality',
+  'confidence',
+  'importance',
+  'status',
+  'related',
+  'sources',
+  'supersedes',
+  'superseded_by',
+  'contradicts',
+];
 
 router.get('/api/memory', requireAuth, requireScope('memory:read'), (req, res) => {
   try {
     const vaultDir = resolveVaultFromQuery(req);
     let list = nodes(vaultDir);
 
-    const { q, category, tag, limit = '200', offset = '0' } = req.query;
+    const { q, category, tag, status, limit = '200', offset = '0' } = req.query;
 
     if (q) {
       const query = String(q).toLowerCase();
@@ -98,6 +122,7 @@ router.get('/api/memory', requireAuth, requireScope('memory:read'), (req, res) =
       );
     }
     if (category) list = list.filter(n => n.category === category);
+    if (status) list = list.filter(n => n.status === status);
     if (tag) list = list.filter(n => (n.tags || []).includes(tag));
 
     const total = list.length;
@@ -154,8 +179,15 @@ router.post('/api/memory', requireAuth, requireScope('memory:write'), (req, res)
       if (req.body[key] !== undefined) node[key] = req.body[key];
     }
 
-    writeNode(node, vaultDir);
-    invalidate();
+    const vaultResult = writeNodeValidated(node, vaultDir);
+    if (!vaultResult.success) {
+      return res.status(422).json({
+        error: 'Validation failed',
+        validation: vaultResult.validation,
+        repair: vaultResult.repair,
+      });
+    }
+    invalidate(vaultDir);
     triggerMutation(node, vaultDir);
     res.status(201).json(sanitizeNode(node));
   } catch (err) {
@@ -178,8 +210,15 @@ router.put('/api/memory/:slug', requireAuth, requireScope('memory:write'), (req,
       if (req.body[key] !== undefined) node[key] = req.body[key];
     }
 
-    writeNode(node, vaultDir);
-    invalidate();
+    const vaultResult = writeNodeValidated(node, vaultDir);
+    if (!vaultResult.success) {
+      return res.status(422).json({
+        error: 'Validation failed',
+        validation: vaultResult.validation,
+        repair: vaultResult.repair,
+      });
+    }
+    invalidate(vaultDir);
     triggerMutation(node, vaultDir);
     res.json(sanitizeNode(node));
   } catch (err) {
@@ -202,7 +241,7 @@ router.patch('/api/memory/:slug', requireAuth, requireScope('memory:write'), (re
       content:  actualContent,
     });
     updated.tags = tags ?? existing.tags ?? [];
-    updated.created_at = existing.created_at;
+    updated.created = existing.created;
 
     for (const key of PASSTHROUGH_FIELDS) {
       if (existing[key] !== undefined) updated[key] = existing[key];
@@ -211,8 +250,15 @@ router.patch('/api/memory/:slug', requireAuth, requireScope('memory:write'), (re
       if (req.body[key] !== undefined) updated[key] = req.body[key];
     }
 
-    writeNode(updated, vaultDir);
-    invalidate();
+    const vaultResult = writeNodeValidated(updated, vaultDir);
+    if (!vaultResult.success) {
+      return res.status(422).json({
+        error: 'Validation failed',
+        validation: vaultResult.validation,
+        repair: vaultResult.repair,
+      });
+    }
+    invalidate(vaultDir);
     triggerMutation(updated, vaultDir);
     res.json(sanitizeNode(updated));
   } catch (err) {
@@ -238,7 +284,7 @@ router.delete('/api/memory/:slug', requireAuth, requireScope('memory:write'), (r
         }
       }
     }
-    invalidate();
+    invalidate(vaultDir);
     triggerMutation(null, vaultDir);
     res.json({ deleted: true, slug: req.params.slug });
   } catch (err) {

package/src/server/routes/sessions.mjs

@@ -205,7 +205,12 @@ router.get('/api/sessions/:id', requireAuth, requireScope('memory:read'), (req,
 router.post('/api/sessions/ingest', ingestRateLimiter(), requireAuth, requireScope('memory:write'), (req, res) => {
   try {
     const body = req.body || {};
-    const source = body.source || 'api';
+    const source = String(body.source || 'api')
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 48) || 'api';
 
     let messages;
     if (body.content && typeof body.content === 'string') {
@@ -333,4 +338,3 @@ router.delete('/api/sessions/:id', requireAuth, requireScope('memory:write'), (r
 });
 
 export { router as sessionsRouter, drainActiveEmbeddings };
-

package/src/server/routes/share.mjs

@@ -8,7 +8,8 @@
 
 import express from 'express';
 import crypto from 'node:crypto';
-import { createMemoryNode, writeNode } from '../../core/vault.mjs';
+import { createMemoryNode } from '../../core/vault.mjs';
+import { writeNodeValidated } from '../../core/validated-write.mjs';
 import { invalidate } from '../../core/vault-cache.mjs';
 import { addToQueue } from '../../core/research-queue.mjs';
 import { requireAuth, requireScope } from '../auth.mjs';
@@ -121,7 +122,13 @@ router.post('/api/share', requireAuth, requireScope('memory:write'), async (req,
       }];
     }
 
-    writeNode(node, vaultDir);
+    const vaultResult = writeNodeValidated(node, vaultDir);
+    if (!vaultResult.success) {
+      return res.status(422).json({
+        error: 'Validation failed',
+        validation: vaultResult.validation,
+      });
+    }
     invalidate();
 
     // Mark extension as connected when share comes from the extension