nubos-pilot 1.2.1 → 1.2.3

package/lib/learnings/capture-ledger.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Rate-limit ledger for Stop-hook learning auto-capture. Mirrors the ADR-0020
+// security ledger's posture (sliding per-hour window + consecutive-stop streak)
+// but is its own concern and its own file. Per-session JSON under the OS temp
+// dir; a session that never stops leaves nothing behind worth cleaning.
+
+const DIR = path.join(os.tmpdir(), 'nubos-pilot-learnings');
+
+function sanitizeSid(sid) {
+  return String(sid || 'nosid').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+
+function ledgerPath(sid) {
+  return path.join(DIR, sanitizeSid(sid) + '.json');
+}
+
+function _read(sid) {
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath(sid), 'utf-8'));
+  } catch {
+    return { session_id: sanitizeSid(sid), created_at: Date.now(), capture_times: [], stop_streak: 0 };
+  }
+}
+
+function _write(sid, l) {
+  try {
+    fs.mkdirSync(DIR, { recursive: true });
+    fs.writeFileSync(ledgerPath(sid), JSON.stringify(l), 'utf-8');
+  } catch { /* a rate-limit ledger must never break the session */ }
+}
+
+/**
+ * Record an attempt to auto-capture on this session's Stop. Returns whether the
+ * capture is allowed under both caps. The per-hour window prevents runaway cost;
+ * the in-a-row streak prevents back-to-back Stops (e.g. a tight edit loop) each
+ * firing an extraction.
+ * @returns {{allowed: boolean, count: number, streak: number, reason?: string}}
+ */
+function tryRecordCapture(sid, opts) {
+  const maxPerHour = opts && Number.isFinite(opts.maxPerHour) ? opts.maxPerHour : 10;
+  const maxStreak = opts && Number.isFinite(opts.maxStreak) ? opts.maxStreak : 3;
+  const now = Date.now();
+  const hourAgo = now - 3600 * 1000;
+
+  const l = _read(sid);
+  l.capture_times = (Array.isArray(l.capture_times) ? l.capture_times : []).filter((t) => t > hourAgo);
+  l.stop_streak = Number.isFinite(l.stop_streak) ? l.stop_streak : 0;
+
+  if (l.capture_times.length >= maxPerHour) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'per-hour-cap' };
+  }
+  if (l.stop_streak >= maxStreak) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'streak-cap' };
+  }
+
+  l.capture_times.push(now);
+  l.stop_streak += 1;
+  _write(sid, l);
+  return { allowed: true, count: l.capture_times.length, streak: l.stop_streak };
+}
+
+/** Reset the consecutive-stop streak — call after a user prompt (real activity). */
+function resetStreak(sid) {
+  const l = _read(sid);
+  l.stop_streak = 0;
+  _write(sid, l);
+}
+
+function removeLedger(sid) {
+  try { fs.unlinkSync(ledgerPath(sid)); } catch {}
+}
+
+module.exports = { tryRecordCapture, resetStreak, removeLedger, ledgerPath, sanitizeSid, _read };

package/lib/learnings/capture-ledger.test.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { tryRecordCapture, resetStreak, removeLedger } = require('./capture-ledger.cjs');
+
+function _sid(name) { return 'np-test-ledger-' + name + '-' + process.pid; }
+
+test('CL-1: streak cap blocks after maxStreak consecutive stops', () => {
+  const sid = _sid('streak');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'streak-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-2: resetStreak clears the streak so capture is allowed again', () => {
+  const sid = _sid('reset');
+  removeLedger(sid);
+  try {
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, false);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, true);
+  } finally { removeLedger(sid); }
+});
+
+test('CL-3: per-hour cap blocks regardless of streak resets', () => {
+  const sid = _sid('hour');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'per-hour-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-4: a fresh session starts allowed', () => {
+  const sid = _sid('fresh');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, {}).allowed, true);
+  } finally { removeLedger(sid); }
+});

package/lib/learnings/extract.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const git = require('../git.cjs');
+const knowledgeAdapter = require('../knowledge-adapter.cjs');
+
+// Stop-hook learning auto-capture (ECC continuous-learning, np-native). A
+// background worker spawns the read-only np-learnings-extractor headlessly over
+// the turn's diff; it returns atomic {pattern, outcome} candidates which we fold
+// into the existing learnings store via the knowledge adapter — the same store
+// /np:execute-phase already auto-logs into. Mirrors lib/security/review.cjs.
+
+const EXTRACTOR_AGENT = 'np-learnings-extractor';
+const MAX_DIFF_BYTES = 64 * 1024;
+const MAX_UNTRACKED_BYTES = 12 * 1024;
+const MAX_CANDIDATES = 5;
+const MAX_PATTERN_LEN = 2000;
+const MAX_OUTCOME_LEN = 2000;
+const VALID_OUTCOMES = new Set(['verified', 'failed', 'reverted', 'partial']);
+
+function isRepo(cwd) {
+  const r = git.runGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+  return r.ok && String(r.stdout).trim() === 'true';
+}
+
+function _lines(stdout) {
+  return String(stdout || '').split(/\r?\n/).filter(Boolean);
+}
+
+// "What changed this session": last commit (git show HEAD) plus any uncommitted
+// working changes and untracked files, each capped. No baseline tracking —
+// learnings are advisory, so a slightly wider window is acceptable.
+function computeTurnDiff(cwd, maxFiles) {
+  const cap = Number.isFinite(maxFiles) ? maxFiles : 30;
+  const committedNames = git.runGit(['diff-tree', '--no-commit-id', '--name-only', '-r', '--root', 'HEAD'], { cwd });
+  const workingNames = git.runGit(['--no-pager', 'diff', '--name-only'], { cwd });
+  const untracked = git.runGit(['ls-files', '--others', '--exclude-standard'], { cwd });
+
+  const files = [...new Set([
+    ..._lines(committedNames.stdout),
+    ..._lines(workingNames.stdout),
+    ..._lines(untracked.stdout),
+  ])];
+  const uniqueFiles = files.slice(0, cap);
+  const truncatedFiles = files.length > cap;
+
+  let diffText = '';
+  const show = git.runGit(['--no-pager', 'show', '--no-color', 'HEAD'], { cwd });
+  if (show.ok) diffText += String(show.stdout || '').slice(0, MAX_DIFF_BYTES);
+  const working = git.runGit(['--no-pager', 'diff', '--no-color'], { cwd });
+  if (working.ok && diffText.length < MAX_DIFF_BYTES) {
+    diffText += '\n' + String(working.stdout || '').slice(0, MAX_DIFF_BYTES - diffText.length);
+  }
+
+  let untrackedBudget = MAX_UNTRACKED_BYTES;
+  for (const f of _lines(untracked.stdout)) {
+    if (untrackedBudget <= 0) break;
+    let body = '';
+    try { body = fs.readFileSync(path.join(cwd, f), 'utf-8'); } catch { continue; }
+    const chunk = '\n--- new file: ' + f + ' ---\n' + body.slice(0, untrackedBudget);
+    diffText += chunk;
+    untrackedBudget -= chunk.length;
+  }
+
+  return { files: uniqueFiles, truncatedFiles, diffText };
+}
+
+function buildExtractorPrompt(opts) {
+  const o = opts || {};
+  const parts = [];
+  parts.push('<learning_capture>');
+  parts.push('You are running in learning-capture mode. Read the diff below — the work this session produced — and extract at most ' + MAX_CANDIDATES + ' ATOMIC, REUSABLE engineering learnings.');
+  parts.push('');
+  parts.push('A good learning is a durable, transferable rule a future agent on a SIMILAR task would benefit from — a convention discovered, a pitfall avoided, a fix that generalises. NOT a narration of what changed, NOT project-specific trivia, NOT anything obvious from reading the code.');
+  parts.push('');
+  parts.push('Each learning is one {pattern, outcome} pair:');
+  parts.push('- pattern: the reusable rule, imperative and self-contained (e.g. "use jose for JWT verification, never hand-roll HS256").');
+  parts.push('- outcome: one of verified | failed | reverted | partial — how it played out THIS session.');
+  parts.push('');
+  parts.push('If nothing meets the bar, return an empty list. Quality over quantity — zero is a valid, common answer.');
+  parts.push('');
+  parts.push('Changed files (' + o.files.length + (o.truncatedFiles ? '+, truncated' : '') + '):');
+  parts.push(o.files.map((f) => '- ' + f).join('\n'));
+  parts.push('');
+  parts.push('Diff:');
+  parts.push('```diff');
+  parts.push(o.diffText);
+  parts.push('```');
+  parts.push('');
+  parts.push('Output ONLY a single JSON object (no prose, no markdown fence):');
+  parts.push('{"learnings":[{"pattern":"...","outcome":"verified|failed|reverted|partial"}]}');
+  parts.push('</learning_capture>');
+  return parts.join('\n');
+}
+
+function _tryParseJson(s) { try { return JSON.parse(s); } catch { return null; } }
+function _stripFence(s) {
+  const m = String(s).match(/```(?:json)?\s*([\s\S]*?)```/);
+  return m ? m[1] : s;
+}
+
+function parseExtractorOutput(raw) {
+  if (!raw || typeof raw !== 'string') return { candidates: [], parse_ok: false };
+  let resultText = raw;
+  const outer = _tryParseJson(raw);
+  if (outer && typeof outer === 'object' && typeof outer.result === 'string') resultText = outer.result;
+
+  let env = _tryParseJson(resultText);
+  if (!env) env = _tryParseJson(_stripFence(resultText));
+  if (!env || typeof env !== 'object' || !Array.isArray(env.learnings)) {
+    return { candidates: [], parse_ok: false };
+  }
+  const candidates = env.learnings
+    .filter((l) => l && typeof l === 'object' && typeof l.pattern === 'string' && l.pattern.trim())
+    .map((l) => ({
+      pattern: l.pattern.trim().slice(0, MAX_PATTERN_LEN),
+      outcome: VALID_OUTCOMES.has(String(l.outcome)) ? String(l.outcome) : 'verified',
+    }))
+    .slice(0, MAX_CANDIDATES);
+  return { candidates, parse_ok: true };
+}
+
+function _defaultSpawn(promptText, opts) {
+  const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
+  const tmp = os.tmpdir();
+  const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const promptPath = path.join(tmp, 'np-learn-prompt-' + tag + '.txt');
+  const outputPath = path.join(tmp, 'np-learn-out-' + tag + '.json');
+  fs.writeFileSync(promptPath, promptText, 'utf-8');
+  try {
+    spawnHeadless.run(
+      ['--agent', EXTRACTOR_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
+        '--timeout-ms', String(opts.timeoutMs)],
+      { cwd: opts.cwd, stdout: { write: () => {} } },
+    );
+    return fs.readFileSync(outputPath, 'utf-8');
+  } finally {
+    try { fs.unlinkSync(promptPath); } catch {}
+    try { fs.unlinkSync(outputPath); } catch {}
+  }
+}
+
+function runExtract(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const config = o.config || {};
+  const spawn = typeof o.spawnImpl === 'function' ? o.spawnImpl : _defaultSpawn;
+  const logImpl = typeof o.logImpl === 'function'
+    ? o.logImpl
+    : (cand) => knowledgeAdapter.getAdapter(cwd).log({ pattern: cand.pattern, outcome: cand.outcome });
+
+  if (!isRepo(cwd)) return { ran: false, reason: 'not-a-repo', logged: 0 };
+
+  const maxFiles = Number.isFinite(config.max_files) ? config.max_files : 30;
+  const diff = computeTurnDiff(cwd, maxFiles);
+  if (!String(diff.diffText).trim()) {
+    return { ran: true, logged: 0, reason: 'empty-diff' };
+  }
+
+  const promptText = buildExtractorPrompt(diff);
+  let raw = '';
+  try {
+    raw = spawn(promptText, { cwd, timeoutMs: config.timeout_ms || 120000 });
+  } catch {
+    return { ran: true, logged: 0, reason: 'spawn-failed' };
+  }
+
+  const parsed = parseExtractorOutput(raw);
+  if (!parsed.parse_ok) return { ran: true, logged: 0, reason: 'parse-failed' };
+
+  let logged = 0;
+  for (const cand of parsed.candidates) {
+    try { logImpl(cand); logged += 1; } catch { /* one bad candidate must not abort the rest */ }
+  }
+  return { ran: true, logged, candidates: parsed.candidates.length, reason: 'ok' };
+}
+
+module.exports = {
+  EXTRACTOR_AGENT,
+  isRepo,
+  computeTurnDiff,
+  buildExtractorPrompt,
+  parseExtractorOutput,
+  runExtract,
+  MAX_CANDIDATES,
+  VALID_OUTCOMES,
+};

package/lib/learnings/extract.test.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const cp = require('node:child_process');
+const extract = require('./extract.cjs');
+
+function _gitRepo(withCommit) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-extract-'));
+  const run = (args) => cp.spawnSync('git', args, { cwd: dir, encoding: 'utf-8' });
+  run(['init', '-q']);
+  run(['config', 'user.email', 'test@example.com']);
+  run(['config', 'user.name', 'Test']);
+  run(['config', 'commit.gpgsign', 'false']);
+  if (withCommit) {
+    fs.writeFileSync(path.join(dir, 'a.js'), 'function add(a,b){return a+b;}\n');
+    run(['add', '-A']);
+    run(['commit', '-q', '-m', 'add helper']);
+  }
+  return dir;
+}
+
+test('EX-1: buildExtractorPrompt frames a learning_capture block with diff + files', () => {
+  const p = extract.buildExtractorPrompt({ files: ['a.js'], truncatedFiles: false, diffText: '+ code' });
+  assert.match(p, /<learning_capture>/);
+  assert.match(p, /a\.js/);
+  assert.match(p, /```diff/);
+  assert.match(p, /"learnings"/);
+});
+
+test('EX-2: parseExtractorOutput unwraps {result} envelope', () => {
+  const raw = JSON.stringify({ result: JSON.stringify({ learnings: [{ pattern: 'use jose for jwt', outcome: 'verified' }] }) });
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.parse_ok, true);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].pattern, 'use jose for jwt');
+});
+
+test('EX-3: parseExtractorOutput strips a markdown fence', () => {
+  const raw = '```json\n{"learnings":[{"pattern":"p","outcome":"failed"}]}\n```';
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].outcome, 'failed');
+});
+
+test('EX-4: invalid outcome defaults to verified; empty pattern dropped', () => {
+  const raw = JSON.stringify({ learnings: [
+    { pattern: 'good', outcome: 'banana' },
+    { pattern: '   ', outcome: 'verified' },
+  ] });
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].outcome, 'verified');
+});
+
+test('EX-5: caps candidates at MAX_CANDIDATES', () => {
+  const many = Array.from({ length: 9 }, (_, i) => ({ pattern: 'p' + i, outcome: 'verified' }));
+  const r = extract.parseExtractorOutput(JSON.stringify({ learnings: many }));
+  assert.strictEqual(r.candidates.length, extract.MAX_CANDIDATES);
+});
+
+test('EX-6: non-JSON output → parse_ok false', () => {
+  assert.strictEqual(extract.parseExtractorOutput('totally not json').parse_ok, false);
+  assert.strictEqual(extract.parseExtractorOutput('').parse_ok, false);
+});
+
+test('EX-7: runExtract on a non-repo returns not-a-repo, logs nothing', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-norepo-'));
+  try {
+    const logged = [];
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: (c) => logged.push(c) });
+    assert.strictEqual(r.ran, false);
+    assert.strictEqual(r.reason, 'not-a-repo');
+    assert.strictEqual(logged.length, 0);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-8: runExtract on empty repo (no commit, no changes) → empty-diff', () => {
+  const dir = _gitRepo(false);
+  try {
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: () => {} });
+    assert.strictEqual(r.ran, true);
+    assert.strictEqual(r.reason, 'empty-diff');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-9: runExtract over a commit logs parsed candidates', () => {
+  const dir = _gitRepo(true);
+  try {
+    const logged = [];
+    const r = extract.runExtract({
+      cwd: dir,
+      spawnImpl: () => JSON.stringify({ result: JSON.stringify({ learnings: [
+        { pattern: 'keep add() pure and total', outcome: 'verified' },
+      ] }) }),
+      logImpl: (c) => logged.push(c),
+    });
+    assert.strictEqual(r.ran, true);
+    assert.strictEqual(r.logged, 1);
+    assert.strictEqual(logged[0].pattern, 'keep add() pure and total');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-10: runExtract with unparseable spawn output → parse-failed, no log', () => {
+  const dir = _gitRepo(true);
+  try {
+    const logged = [];
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => 'garbage', logImpl: (c) => logged.push(c) });
+    assert.strictEqual(r.reason, 'parse-failed');
+    assert.strictEqual(logged.length, 0);
+  } 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) {