nubos-pilot 1.2.0 → 1.2.2

package/lib/install/claude-hooks.cjs

@@ -16,8 +16,21 @@ const { atomicWriteFileSync, NubosPilotError, withFileLock } = require('../core.
 
 const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.cjs';
 const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.cjs';
+const SECURITY_HOOK_REL = '.claude/nubos-pilot/hooks/np-security-hook.cjs';
 const NP_STATUSLINE_MARKER = 'np-statusline.';
 const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.';
+const NP_SECURITY_MARKER = 'np-security-hook.';
+
+// ADR-0020: in-session security review layer. One DRY hook script, registered
+// against five Claude Code lifecycle events, differentiated by a trailing verb.
+const SECURITY_HOOKS = Object.freeze([
+  { verb: 'session-start', event: 'SessionStart',    matcher: undefined },
+  { verb: 'baseline',      event: 'UserPromptSubmit', matcher: undefined },
+  { verb: 'scan',          event: 'PostToolUse',      matcher: 'Edit|Write|MultiEdit|NotebookEdit' },
+  { verb: 'review',        event: 'Stop',             matcher: undefined },
+  { verb: 'commit',        event: 'PostToolUse',      matcher: 'Bash' },
+]);
+const SECURITY_EVENTS = Object.freeze(['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse']);
 
 function _settingsPath(scope, projectRoot) {
   if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
@@ -101,6 +114,64 @@ function _installPostToolUse(settings, cmd) {
   return { action: 'installed' };
 }
 
+function _verbOf(command) {
+  const m = String(command).match(/"\s+([a-z-]+)\s*$/);
+  return m ? m[1] : null;
+}
+
+function _installVerbHook(settings, eventName, matcher, cmd, verb) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks[eventName])) settings.hooks[eventName] = [];
+  const list = settings.hooks[eventName];
+  for (const entry of list) {
+    const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+    for (const h of hooks) {
+      if (h && typeof h.command === 'string' && h.command.includes(NP_SECURITY_MARKER) && _verbOf(h.command) === verb) {
+        h.command = cmd;
+        h.type = 'command';
+        if (matcher !== undefined) entry.matcher = matcher;
+        return { action: 'updated' };
+      }
+    }
+  }
+  const entry = matcher !== undefined
+    ? { matcher, hooks: [{ type: 'command', command: cmd }] }
+    : { hooks: [{ type: 'command', command: cmd }] };
+  list.push(entry);
+  return { action: 'installed' };
+}
+
+function _installSecurity(settings, scope, projectRoot) {
+  const base = _hookCommand(SECURITY_HOOK_REL, scope, projectRoot);
+  const results = {};
+  for (const h of SECURITY_HOOKS) {
+    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb);
+  }
+  return results;
+}
+
+function _removeSecurity(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') return { action: 'absent' };
+  let removed = 0;
+  for (const eventName of SECURITY_EVENTS) {
+    if (!Array.isArray(settings.hooks[eventName])) continue;
+    const filtered = [];
+    for (const entry of settings.hooks[eventName]) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      const kept = hooks.filter((h) => !(h && typeof h.command === 'string' && h.command.includes(NP_SECURITY_MARKER)));
+      if (kept.length > 0) {
+        filtered.push(kept.length === hooks.length ? entry : Object.assign({}, entry, { hooks: kept }));
+      } else {
+        removed++;
+      }
+    }
+    settings.hooks[eventName] = filtered;
+    if (filtered.length === 0) delete settings.hooks[eventName];
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  return { action: removed > 0 ? 'removed' : 'absent' };
+}
+
 function _removeStatusLine(settings) {
   const existing = settings.statusLine;
   if (existing && typeof existing === 'object'
@@ -140,13 +211,19 @@ function installClaudeHooks(opts) {
   const which = o.which || 'both';
   const settingsPath = _settingsPath(scope, projectRoot);
 
+  const wantStatusline = which === 'statusline' || which === 'both' || which === 'all';
+  const wantCtxMonitor = which === 'ctx-monitor' || which === 'both' || which === 'all';
+  const wantSecurity = which === 'security' || which === 'all';
+
   const statuslineCmd = _hookCommand(STATUSLINE_REL, scope, projectRoot);
   const ctxMonitorCmd = _hookCommand(CTX_MONITOR_REL, scope, projectRoot);
 
-  const statuslineAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, STATUSLINE_REL);
-  const ctxMonitorAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, CTX_MONITOR_REL);
+  const base = scope === 'global' ? os.homedir() : projectRoot;
+  const statuslineAbs = path.join(base, STATUSLINE_REL);
+  const ctxMonitorAbs = path.join(base, CTX_MONITOR_REL);
+  const securityAbs = path.join(base, SECURITY_HOOK_REL);
 
-  if (which === 'statusline' || which === 'both') {
+  if (wantStatusline) {
     if (!fs.existsSync(statuslineAbs)) {
       throw new NubosPilotError(
         'claude-hooks-script-missing',
@@ -155,7 +232,7 @@ function installClaudeHooks(opts) {
       );
     }
   }
-  if (which === 'ctx-monitor' || which === 'both') {
+  if (wantCtxMonitor) {
     if (!fs.existsSync(ctxMonitorAbs)) {
       throw new NubosPilotError(
         'claude-hooks-script-missing',
@@ -164,6 +241,15 @@ function installClaudeHooks(opts) {
       );
     }
   }
+  if (wantSecurity) {
+    if (!fs.existsSync(securityAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Security hook script not found: ' + securityAbs,
+        { script: securityAbs },
+      );
+    }
+  }
 
   fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
 
@@ -171,12 +257,15 @@ function installClaudeHooks(opts) {
     const settings = _readJsonSafe(settingsPath);
     const results = {};
 
-    if (which === 'statusline' || which === 'both') {
+    if (wantStatusline) {
       results.statusline = _installStatusLine(settings, statuslineCmd, force);
     }
-    if (which === 'ctx-monitor' || which === 'both') {
+    if (wantCtxMonitor) {
       results.ctxMonitor = _installPostToolUse(settings, ctxMonitorCmd);
     }
+    if (wantSecurity) {
+      results.security = _installSecurity(settings, scope, projectRoot);
+    }
 
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
 
@@ -190,13 +279,14 @@ function uninstallClaudeHooks(opts) {
   const projectRoot = o.projectRoot || process.cwd();
   const scope = o.scope === 'global' ? 'global' : 'local';
   const settingsPath = _settingsPath(scope, projectRoot);
-  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' } } };
+  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' }, security: { action: 'absent' } } };
 
   return withFileLock(settingsPath, () => {
     const settings = _readJsonSafe(settingsPath);
     const results = {
       statusline: _removeStatusLine(settings),
       ctxMonitor: _removePostToolUse(settings),
+      security: _removeSecurity(settings),
     };
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
     atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -209,8 +299,11 @@ module.exports = {
   uninstallClaudeHooks,
   STATUSLINE_REL,
   CTX_MONITOR_REL,
+  SECURITY_HOOK_REL,
   NP_STATUSLINE_MARKER,
   NP_CTX_MONITOR_MARKER,
+  NP_SECURITY_MARKER,
+  SECURITY_HOOKS,
   _settingsPath,
   _hookCommand,
 };

package/lib/install/claude-hooks.test.cjs

@@ -225,3 +225,99 @@ test('claude-hooks: settings file with only whitespace is treated as empty', ()
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+function _mkSandboxAll() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-all-'));
+  const hooksDir = path.join(dir, '.claude', 'nubos-pilot', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  for (const f of ['np-statusline.cjs', 'np-ctx-monitor.cjs', 'np-security-hook.cjs']) {
+    fs.writeFileSync(path.join(hooksDir, f), '// stub\n');
+  }
+  return dir;
+}
+
+test('claude-hooks SEC: which=all registers all five security lifecycle hooks', () => {
+  const dir = _mkSandboxAll();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    const r = res.results.security;
+    assert.equal(r['session-start'].action, 'installed');
+    assert.equal(r.baseline.action, 'installed');
+    assert.equal(r.scan.action, 'installed');
+    assert.equal(r.review.action, 'installed');
+    assert.equal(r.commit.action, 'installed');
+    const s = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(s.hooks.SessionStart[0].hooks[0].command.replace(/.*np-security-hook\.cjs"\s*/, '').trim(), 'session-start');
+    assert.equal(s.hooks.UserPromptSubmit[0].hooks[0].command.trim().endsWith('baseline'), true);
+    assert.equal(s.hooks.Stop[0].hooks[0].command.trim().endsWith('review'), true);
+    const ptu = s.hooks.PostToolUse;
+    const scan = ptu.find((e) => e.matcher === 'Edit|Write|MultiEdit|NotebookEdit');
+    const commit = ptu.find((e) => e.matcher === 'Bash');
+    assert.ok(scan && scan.hooks[0].command.trim().endsWith('scan'));
+    assert.ok(commit && commit.hooks[0].command.trim().endsWith('commit'));
+    assert.ok(ptu.find((e) => e.matcher === '.*'), 'ctx-monitor still present under all');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks SEC: re-install is idempotent (no duplicate entries)', () => {
+  const dir = _mkSandboxAll();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    const res2 = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    assert.equal(res2.results.security.scan.action, 'updated');
+    const s = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
+    assert.equal(s.hooks.SessionStart.length, 1);
+    assert.equal(s.hooks.Stop.length, 1);
+    assert.equal(s.hooks.PostToolUse.filter((e) => e.hooks[0].command.includes('np-security-hook.')).length, 2);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks SEC: which=both does NOT install security hooks (legacy unchanged)', () => {
+  const dir = _mkSandboxAll();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'both' });
+    assert.equal(res.results.security, undefined);
+    const s = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.ok(!s.hooks.SessionStart);
+    assert.ok(!s.hooks.Stop);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks SEC: uninstall removes security hooks but preserves foreign ones', () => {
+  const dir = _mkSandboxAll();
+  try {
+    const settingsPath = path.join(dir, '.claude', 'settings.local.json');
+    fs.writeFileSync(settingsPath, JSON.stringify({
+      hooks: { Stop: [{ hooks: [{ type: 'command', command: 'echo foreign-stop' }] }] },
+    }));
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    const res = mod.uninstallClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.security.action, 'removed');
+    const s = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    assert.equal(s.hooks.Stop.length, 1);
+    assert.equal(s.hooks.Stop[0].hooks[0].command, 'echo foreign-stop');
+    assert.ok(!s.hooks.SessionStart, 'our SessionStart removed');
+    assert.ok(!s.hooks.PostToolUse || !s.hooks.PostToolUse.some((e) => e.hooks[0].command.includes('np-security-hook.')));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('claude-hooks SEC: which=security missing script throws structured error', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-nosec-'));
+  fs.mkdirSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks'), { recursive: true });
+  try {
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'security' }),
+      (err) => err && err.code === 'claude-hooks-script-missing',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/learnings.cjs

@@ -6,6 +6,10 @@ const crypto = require('node:crypto');
 
 const { projectStateDir, atomicWriteFileSync, withFileLock, NubosPilotError, safeAssign } = require('./core.cjs');
 const { TASK_ID_RE, MILESTONE_ID_RE } = require('./ids.cjs');
+const { assertValid } = require('./validate.cjs');
+const { runMigrators } = require('./migrate.cjs');
+
+const STORE_SCHEMA = 'learnings.v1';
 
 const STOPWORDS = new Set([
   'the','a','an','of','to','in','on','for','and','or','is','are','was','were',
@@ -96,14 +100,7 @@ function _readStore(cwd) {
     );
   }
   if (obj.version === STORE_VERSION) {
-    if (!Array.isArray(obj.learnings)) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings.json missing learnings[] array',
-        { path: p, version: obj.version },
-      );
-    }
-    _assertLearningRecords(obj.learnings, p);
+    assertValid(obj, STORE_SCHEMA, 'learnings-store-corrupt', { path: p });
     return obj;
   }
   const migrated = _migrate(obj, p);
@@ -120,99 +117,26 @@ function _readStore(cwd) {
   );
 }
 
-const _REQUIRED_LEARNING_FIELDS = ['fingerprint', 'pattern', 'outcome', 'occurrence', 'first_seen', 'last_seen'];
-
 function _assertLearningRecords(records, p) {
-  for (let i = 0; i < records.length; i += 1) {
-    const r = records[i];
-    if (!r || typeof r !== 'object' || Array.isArray(r)) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '] is not a JSON object',
-        { path: p, index: i },
-      );
-    }
-    for (const field of _REQUIRED_LEARNING_FIELDS) {
-      if (!(field in r)) {
-        throw new NubosPilotError(
-          'learnings-store-corrupt',
-          'learnings[' + i + '] missing required field "' + field + '"',
-          { path: p, index: i, field, required: _REQUIRED_LEARNING_FIELDS.slice() },
-        );
-      }
-    }
-    if (typeof r.fingerprint !== 'string' || !/^[a-f0-9]{16}$/.test(r.fingerprint)) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].fingerprint must be a 16-char hex string',
-        { path: p, index: i, got: r.fingerprint },
-      );
-    }
-    if (typeof r.occurrence !== 'number' || r.occurrence < 1) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].occurrence must be a positive integer',
-        { path: p, index: i, got: r.occurrence },
-      );
-    }
-    if (typeof r.pattern !== 'string') {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].pattern must be a string',
-        { path: p, index: i, got: typeof r.pattern },
-      );
-    }
-    if (Buffer.byteLength(r.pattern, 'utf-8') > MAX_PATTERN_BYTES) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].pattern exceeds MAX_PATTERN_BYTES',
-        { path: p, index: i, max: MAX_PATTERN_BYTES },
-      );
-    }
-    if (typeof r.outcome !== 'string') {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].outcome must be a string',
-        { path: p, index: i, got: typeof r.outcome },
-      );
-    }
-    if ('tokens' in r && !Array.isArray(r.tokens)) {
-      throw new NubosPilotError(
-        'learnings-store-corrupt',
-        'learnings[' + i + '].tokens, when present, must be an array',
-        { path: p, index: i, got: typeof r.tokens },
-      );
-    }
-    for (const arrField of ['task_ids', 'milestone_ids']) {
-      if (arrField in r && !Array.isArray(r[arrField])) {
-        throw new NubosPilotError(
-          'learnings-store-corrupt',
-          'learnings[' + i + '].' + arrField + ', when present, must be an array',
-          { path: p, index: i, field: arrField, got: typeof r[arrField] },
-        );
-      }
-    }
-  }
-}
-
-function _migrate(obj, p, migrators) {
-  const reg = migrators || MIGRATORS;
-  let cur = obj;
-  while (cur && cur.version !== STORE_VERSION) {
-    const next = reg[cur.version];
-    if (typeof next !== 'function') return null;
-    cur = next(cur);
-    if (!cur || typeof cur !== 'object') return null;
-  }
-  if (!Array.isArray(cur.learnings)) {
+  if (!Array.isArray(records)) {
     throw new NubosPilotError(
       'learnings-store-corrupt',
-      'migrator produced invalid shape (missing learnings[])',
+      'learnings[] must be an array',
       { path: p },
     );
   }
-  _assertLearningRecords(cur.learnings, p);
-  return cur;
+  assertValid({ version: STORE_VERSION, learnings: records }, STORE_SCHEMA, 'learnings-store-corrupt', { path: p });
+}
+
+function _migrate(obj, p, migrators) {
+  return runMigrators(obj, {
+    versionField: 'version',
+    targetVersion: STORE_VERSION,
+    migrators: migrators || MIGRATORS,
+    schema: STORE_SCHEMA,
+    code: 'learnings-store-corrupt',
+    details: { path: p },
+  });
 }
 
 function _evictIfOverCap(store, opts) {

package/lib/memory.cjs

@@ -4,6 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { atomicWriteFileSync, appendJsonl, withFileLockAsync, NubosPilotError, projectStateDir } = require('./core.cjs');
+const { validate } = require('./validate.cjs');
 
 let _memLog;
 function _log() {
@@ -15,6 +16,19 @@ const TYPE_ENUM = new Set(['learning', 'handoff', 'critic', 'research']);
 const PROVENANCE_ENUM = new Set(['VERIFIED', 'CITED', 'ASSUMED', 'CACHED']);
 const SCHEMA_VERSION = 1;
 
+const RECORD_SCHEMA = 'memory-record.v1';
+const MANIFEST_SCHEMA = 'memory-manifest.v1';
+
+const _RECORD_CODE_BY_FIELD = Object.freeze({
+  type: 'memory-invalid-type',
+  title: 'memory-missing-title',
+  body: 'memory-missing-body',
+  tags: 'memory-invalid-tags',
+  provenance: 'memory-invalid-provenance',
+  id: 'memory-invalid-id',
+  phase: 'memory-invalid-phase',
+});
+
 function _memoryRoot(cwd) {
   return path.join(projectStateDir(cwd || process.cwd()), 'memory');
 }
@@ -24,38 +38,14 @@ function _indexPath(cwd) { return path.join(_memoryRoot(cwd), 'index.usearch');
 function _manifestPath(cwd) { return path.join(_memoryRoot(cwd), 'manifest.json'); }
 
 function _validateRecord(record) {
-  if (!record || typeof record !== 'object') {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
     throw new NubosPilotError('memory-invalid-record', 'record must be object', {});
   }
-  if (typeof record.type !== 'string' || !TYPE_ENUM.has(record.type)) {
-    throw new NubosPilotError(
-      'memory-invalid-type',
-      `type must be one of [${[...TYPE_ENUM].join(', ')}]`,
-      { type: record.type },
-    );
-  }
-  if (typeof record.title !== 'string' || record.title.length === 0) {
-    throw new NubosPilotError('memory-missing-title', 'title required as non-empty string', {});
-  }
-  if (typeof record.body !== 'string') {
-    throw new NubosPilotError('memory-missing-body', 'body required as string', { type: typeof record.body });
-  }
-  if (record.tags !== undefined && record.tags !== null && !Array.isArray(record.tags)) {
-    throw new NubosPilotError('memory-invalid-tags', 'tags must be array of strings or null', {});
-  }
-  if (record.provenance !== undefined && record.provenance !== null && !PROVENANCE_ENUM.has(record.provenance)) {
-    throw new NubosPilotError(
-      'memory-invalid-provenance',
-      `provenance must be one of [${[...PROVENANCE_ENUM].join(', ')}]`,
-      { provenance: record.provenance },
-    );
-  }
-  if (record.id !== undefined && record.id !== null && typeof record.id !== 'string') {
-    throw new NubosPilotError('memory-invalid-id', 'id must be string or null', { id: record.id });
-  }
-  if (record.phase !== undefined && record.phase !== null && typeof record.phase !== 'string') {
-    throw new NubosPilotError('memory-invalid-phase', 'phase must be string or null', { phase: record.phase });
-  }
+  const errors = validate(record, RECORD_SCHEMA);
+  if (errors.length === 0) return;
+  const first = errors[0];
+  const code = _RECORD_CODE_BY_FIELD[first.field] || 'memory-invalid-record';
+  throw new NubosPilotError(code, first.message, { field: first.field, value: record[first.field] });
 }
 
 function _readRecordsJsonlWithStats(cwd) {
@@ -66,8 +56,11 @@ function _readRecordsJsonlWithStats(cwd) {
   let skipped = 0;
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
-    try { records.push(JSON.parse(line)); }
-    catch { skipped += 1; }
+    let rec;
+    try { rec = JSON.parse(line); }
+    catch { skipped += 1; continue; }
+    if (validate(rec, RECORD_SCHEMA).length > 0) { skipped += 1; continue; }
+    records.push(rec);
   }
   if (skipped > 0) {
     _log().warn('skipped corrupt records.jsonl lines', {
@@ -92,7 +85,19 @@ function _writeManifest(cwd, manifest) {
 function _readManifest(cwd) {
   const p = _manifestPath(cwd);
   if (!fs.existsSync(p)) return null;
-  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
+  let obj;
+  try { obj = JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
+  const errors = validate(obj, MANIFEST_SCHEMA);
+  if (errors.length > 0) {
+    _log().warn('ignoring corrupt memory manifest', {
+      event: 'memory-manifest-corrupt',
+      file: 'manifest.json',
+      violation: errors[0].message,
+      hint: 'manifest will be rewritten on next index/rebuild; run `memory-rebuild` if model/dim changed',
+    });
+    return null;
+  }
+  return obj;
 }
 
 function _embeddingText(record) {

package/lib/messaging.cjs

@@ -4,6 +4,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { atomicWriteFileSync, atomicCreateExclusiveSync, fsyncDir, appendJsonl, withFileLock, NubosPilotError, projectStateDir } = require('./core.cjs');
+const { validate, assertValid } = require('./validate.cjs');
 
 function _runId() {
   try { return require('./run-context.cjs').getRunId(); }
@@ -13,6 +14,8 @@ function _runId() {
 const KIND_ENUM = new Set(['request', 'response', 'notify']);
 const AGENT_RE = /^[a-zA-Z0-9_-]+$/;
 const ID_RE = /^\d+-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MAX_BODY_BYTES = 256 * 1024;
+const MESSAGE_SCHEMA = 'message.v1';
 
 function _messagesRoot(cwd) {
   return path.join(projectStateDir(cwd || process.cwd()), 'messages');
@@ -81,11 +84,11 @@ function _appendManifest(cwd, event) {
 function _readMessageFile(filePath) {
   let raw;
   try { raw = fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
-  try {
-    const parsed = JSON.parse(raw);
-    Object.defineProperty(parsed, '__path', { value: filePath, enumerable: false });
-    return parsed;
-  } catch { return null; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return null; }
+  if (validate(parsed, MESSAGE_SCHEMA).length > 0) return null;
+  Object.defineProperty(parsed, '__path', { value: filePath, enumerable: false });
+  return parsed;
 }
 
 function _scanDir(dir) {
@@ -118,7 +121,6 @@ function send(opts, cwd) {
   if (typeof o.body !== 'string') {
     throw new NubosPilotError('messages-missing-body', 'body required (string, may be empty)', {});
   }
-  const MAX_BODY_BYTES = 256 * 1024;
   if (Buffer.byteLength(o.body, 'utf-8') > MAX_BODY_BYTES) {
     throw new NubosPilotError(
       'messages-body-too-large',
@@ -157,6 +159,7 @@ function send(opts, cwd) {
     in_reply_to: o.in_reply_to || null,
     created_at: createdAt,
   };
+  assertValid(message, MESSAGE_SCHEMA, 'messages-invalid-record', { id });
 
   const workingDir = cwd || process.cwd();
   const dir = _inboxDir(workingDir, o.to);
@@ -472,4 +475,7 @@ module.exports = {
   pendingReplies,
   sweepTaskOnCommit,
   KIND_ENUM,
+  AGENT_RE,
+  ID_RE,
+  MAX_BODY_BYTES,
 };

package/lib/metrics-aggregate.cjs

@@ -5,6 +5,9 @@ const path = require('node:path');
 const readline = require('node:readline');
 const { NubosPilotError, findProjectRoot } = require('./core.cjs');
 const { SAFE_PHASE_RE } = require('./metrics.cjs');
+const { validate } = require('./validate.cjs');
+
+const RECORD_SCHEMA = 'metrics-record.v1';
 
 let _maLog;
 function _log() {
@@ -41,15 +44,24 @@ function _readJsonlLines(filePath, onRecord) {
     rl.on('line', (raw) => {
       const line = String(raw).trim();
       if (!line) return;
+      let rec;
       try {
-        const rec = JSON.parse(line);
-        onRecord(rec);
+        rec = JSON.parse(line);
       } catch (_err) {
         _log().warn('skipping malformed JSONL line', {
           event: 'metrics-aggregate-malformed-line',
           file: require('node:path').basename(filePath),
         });
+        return;
+      }
+      if (validate(rec, RECORD_SCHEMA).length > 0) {
+        _log().warn('skipping schema-invalid JSONL line', {
+          event: 'metrics-aggregate-invalid-line',
+          file: require('node:path').basename(filePath),
+        });
+        return;
       }
+      onRecord(rec);
     });
     rl.on('close', () => resolve());
     rl.on('error', (err) => reject(err));

package/lib/migrate.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+const { assertValid } = require('./validate.cjs');
+
+const MAX_HOPS = 100;
+
+function runMigrators(obj, opts) {
+  const o = opts || {};
+  const versionField = o.versionField || 'version';
+  const target = o.targetVersion;
+  const migrators = o.migrators || {};
+  let cur = obj;
+  let hops = 0;
+  while (cur && typeof cur === 'object' && !Array.isArray(cur) && cur[versionField] !== target) {
+    if (hops >= MAX_HOPS) return null;
+    hops += 1;
+    const key = cur[versionField];
+    if (!Object.prototype.hasOwnProperty.call(migrators, key)) return null;
+    const fn = migrators[key];
+    if (typeof fn !== 'function') return null;
+    cur = fn(cur);
+    if (!cur || typeof cur !== 'object' || Array.isArray(cur)) return null;
+  }
+  if (!cur || typeof cur !== 'object' || Array.isArray(cur)) return null;
+  if (o.schema) assertValid(cur, o.schema, o.code || 'data-migration-invalid', o.details || {});
+  return cur;
+}
+
+module.exports = { runMigrators, MAX_HOPS };