total-recall-brain 3.23.3 → 3.24.0

package/src/core/secrets-env-diff.mjs

@@ -0,0 +1,132 @@
+/**
+ * Compare repo .env files against the secrets store.
+ *
+ * The store is meant to be the SSOT and .env files its projections, but nothing
+ * ever checked that they agreed. Drift is silent and consequential: the same
+ * key can hold a rotated credential in one place and a retired one in the
+ * other, and whichever the process happens to read decides whether a service
+ * works. Length-equal drift is the dangerous kind — same provider, same format,
+ * different key — because it looks like a match in every summary that counts
+ * keys rather than comparing values.
+ *
+ * Reports only shapes and lengths. Secret values never leave this module.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { loadSecrets, listSecretsMeta } from './secrets-store.mjs';
+import { parseEnvText, isCandidateKey } from './env-import.mjs';
+
+/** Values that are obviously templates rather than credentials. */
+const PLACEHOLDER = /^(your[_-]?|xxx+|changeme|<|placeholder|todo|sk-your|example)/i;
+
+export function isPlaceholderValue(value) {
+  const v = String(value || '').trim();
+  if (!v) return true;
+  if (PLACEHOLDER.test(v)) return true;
+  // `..._HERE`, `PUT_KEY_HERE` and friends
+  return /(_|-)?here$/i.test(v);
+}
+
+/**
+ * Classify one key across the two sources.
+ * @returns {'match'|'drift'|'only_env'|'only_store'|'placeholder'}
+ */
+export function classify(envValue, storeValue, keyInStore) {
+  if (envValue !== undefined && isPlaceholderValue(envValue)) return 'placeholder';
+  if (envValue === undefined) return 'only_store';
+  if (!keyInStore) return 'only_env';
+  return String(storeValue) === String(envValue) ? 'match' : 'drift';
+}
+
+/**
+ * Locate the .env files worth comparing, from the project registry plus any
+ * explicit paths. Never hardcodes a repo: registry entries and caller input only.
+ */
+export function resolveEnvFiles(roots = [], filenames = ['.env']) {
+  const files = [];
+  for (const root of roots) {
+    for (const name of filenames) {
+      const candidate = path.join(root, name);
+      if (fs.existsSync(candidate)) files.push(candidate);
+      // Sub-app env files (e.g. a server/ workspace) drift independently.
+      const nested = path.join(root, 'server', name);
+      if (fs.existsSync(nested)) files.push(nested);
+    }
+  }
+  return files;
+}
+
+/**
+ * Diff every candidate secret in the given .env files against the store.
+ */
+/**
+ * Which repo a .env belongs to, for comparison against a secret's binding.
+ * Walks up to the directory holding the file, ignoring a nested app dir.
+ */
+export function repoOfEnvFile(file) {
+  const parts = path.resolve(file).split(path.sep);
+  const idx = parts.lastIndexOf('Github');
+  if (idx !== -1 && parts[idx + 1]) return parts[idx + 1];
+  return path.basename(path.dirname(path.resolve(file)));
+}
+
+export async function diffEnvAgainstStore(brainDir, envFiles) {
+  const store = await loadSecrets(brainDir);
+  const meta = await listSecretsMeta(brainDir).catch(() => []);
+  const bindingOf = new Map(meta.map((m) => [m.key, m.repos || m.repo || null]));
+  const rows = [];
+  const totals = { match: 0, drift: 0, only_env: 0, placeholder: 0, collision: 0 };
+
+  for (const file of envFiles) {
+    let parsed;
+    try {
+      parsed = parseEnvText(fs.readFileSync(file, 'utf8'));
+    } catch (err) {
+      rows.push({ key: '(unreadable)', file, status: 'error', detail: err.message });
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(parsed)) {
+      if (!isCandidateKey(key)) continue;
+      let status = classify(value, store[key], key in store);
+      if (status === 'only_store') continue;
+
+      // A store entry is bound to exactly one repo. When the .env belongs to a
+      // different repo, the two values are not the same credential wearing one
+      // name — they are two products' credentials colliding on a shared
+      // variable name (STRIPE_SECRET_KEY, MAILCOW_API_KEY). Reporting that as
+      // drift invites "fixing" it by overwriting a live key with another
+      // product's.
+      const binding = bindingOf.get(key) || null;
+      const envRepo = repoOfEnvFile(file);
+      const crossProduct = Boolean(
+        status === 'drift' && binding && !String(binding).split(',').includes(envRepo),
+      );
+      if (crossProduct) status = 'collision';
+
+      totals[status] += 1;
+      if (status === 'match') continue;
+      rows.push({
+        key,
+        file,
+        status,
+        binding,
+        envRepo,
+        envLength: String(value ?? '').length,
+        storeLength: key in store ? String(store[key]).length : null,
+        // Equal lengths mean the same credential format — a rotation that
+        // landed on one side only, rather than two unrelated values.
+        sameShape: key in store && String(store[key]).length === String(value ?? '').length,
+      });
+    }
+  }
+
+  rows.sort((a, b) => (a.status === b.status ? a.key.localeCompare(b.key) : a.status.localeCompare(b.status)));
+  return { totals, rows, storeKeyCount: Object.keys(store).filter((k) => !k.startsWith('__')).length };
+}
+
+export function defaultBrainDir() {
+  return path.join(os.homedir(), '.agent', 'skills', 'total-recall');
+}

package/src/core/snapshot.mjs

@@ -22,14 +22,19 @@ export function getSnapshotsDir() {
 }
 
 /**
- * Create a point-in-time snapshot of the memory vault.
+ * Create a point-in-time snapshot of a memory vault.
+ *
+ * `vaultDir` is explicit because this used to always snapshot the global brain
+ * vault no matter which vault the caller was about to modify — so a migration
+ * against a project vault took its safety snapshot of an unrelated vault and
+ * the thing being changed had no backup at all.
  *
  * @param {string} reason - The reason for the snapshot (e.g. 'pre-dream', 'manual')
+ * @param {string} [vaultDir] - Vault to snapshot; defaults to the global brain vault
  * @returns {{ success: boolean, snapshot_id: string, path: string, error?: string }}
  */
-export function createSnapshot(reason = 'manual') {
+export function createSnapshot(reason = 'manual', vaultDir = path.join(brainDir, 'memory-vault')) {
   try {
-    const vaultDir = path.join(brainDir, 'memory-vault');
     const snapshotsDir = getSnapshotsDir();
 
     if (!fs.existsSync(vaultDir)) {
@@ -48,6 +53,7 @@ export function createSnapshot(reason = 'manual') {
       snapshot_id: snapshotId,
       created_at: new Date().toISOString(),
       reason,
+      vault_dir: vaultDir,
     };
     fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2));
 
@@ -91,14 +97,20 @@ export function listSnapshots() {
 }
 
 /**
- * Rollback the memory vault to a specific snapshot.
+ * Rollback a memory vault to a specific snapshot.
+ *
+ * Restores into the vault the snapshot was actually taken from, recorded in its
+ * metadata. This used to always restore into the global brain vault, so rolling
+ * back a project snapshot would have deleted the global vault and unpacked
+ * another project's nodes over it — destroying good data while leaving the
+ * vault in trouble untouched. Snapshots predating the recorded field came from
+ * the global vault, which is the fallback.
  *
  * @param {string} snapshotId - The ID of the snapshot to restore.
  * @returns {{ success: boolean, error?: string }}
  */
 export function rollbackVault(snapshotId) {
   try {
-    const vaultDir = path.join(brainDir, 'memory-vault');
     const snapshotsDir = getSnapshotsDir();
 
     const tarball = path.join(snapshotsDir, `vault-${snapshotId}.tar.gz`);
@@ -106,8 +118,19 @@ export function rollbackVault(snapshotId) {
       return { success: false, error: `Snapshot ${snapshotId} not found.` };
     }
 
-    // Safety measure: take a backup of the CURRENT state before destroying it
-    const preRollback = createSnapshot(`pre-rollback-to-${snapshotId}`);
+    let vaultDir = path.join(brainDir, 'memory-vault');
+    const metaPath = path.join(snapshotsDir, `vault-${snapshotId}.json`);
+    if (fs.existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+        if (meta.vault_dir) vaultDir = meta.vault_dir;
+      } catch (err) {
+        return { success: false, error: `Snapshot ${snapshotId} metadata is unreadable: ${err.message}` };
+      }
+    }
+
+    // Safety measure: back up the CURRENT state of that same vault first
+    const preRollback = createSnapshot(`pre-rollback-to-${snapshotId}`, vaultDir);
     if (!preRollback.success) {
       return { success: false, error: `Failed to create pre-rollback safety snapshot: ${preRollback.error}` };
     }
@@ -124,8 +147,8 @@ export function rollbackVault(snapshotId) {
       throw new Error(`tar extraction failed: ${result.stderr.toString()}`);
     }
 
-    logger.info('snapshot', `Rolled back to snapshot ${snapshotId}`);
-    return { success: true };
+    logger.info('snapshot', `Rolled back ${vaultDir} to snapshot ${snapshotId}`);
+    return { success: true, vault_dir: vaultDir };
   } catch (err) {
     logger.error('snapshot', `Rollback failed: ${err.message}`);
     return { success: false, error: err.message };

package/src/core/ssss-kernel-bridge.mjs

@@ -499,9 +499,27 @@ export function scanDirectCanonicalWrites(rootDir = path.resolve('src'), options
 }
 
 /**
- * Modules that write memory-like markdown without going through Operation Contract.
- * Heuristic: atomicWrite/writeNode call sites outside the approved contract surface.
+ * Modules that write vault nodes without going through the Operation Contract.
+ *
+ * The previous heuristic was wrong in both directions. It flagged any use of
+ * `writeNode(`, which is the *correct* path — vault.writeNode delegates to
+ * writeNodeValidatedAsync — so eleven compliant modules showed up as
+ * violations. And it only matched `atomicWrite(...".md")`, so it missed every
+ * bypass whose target is a variable: dream.writeDailyNote hand-assembled a YAML
+ * string and wrote it to `filePath`, which is exactly the write this gate
+ * exists to catch.
+ *
+ * What actually constitutes a bypass is the write target, not the call name: a
+ * raw write into the vault (memory-vault, vaultDir, a node's own _filepath)
+ * skips validation. Raw writes into the staging areas — memory-inbox/ and
+ * scheduler/queue/ — are legitimate; those files are not vault nodes and are
+ * promoted through the contract later.
  */
+const RAW_WRITE_CALL = /\b(?:atomicWrite|fs\.writeFileSync|writeFileSync)\s*\(/;
+const VAULT_TARGET = /\b(?:vaultDir|vaultRoot|memory-vault|_filepath|_filePath|proposalsDir|dailyDir)\b/;
+const RAW_WRITE_WAIVER = /ssss-raw-write:/;
+const STAGING_TARGET = /\b(?:inboxDir|queueDir|conflictsDir|quarantineDir|INBOX_DIR|QUEUE_DIR|agendaFile|snapshotPath)\b/;
+
 export function listUnapprovedCanonicalWriters(rootDir = path.resolve('src/core')) {
   const approved = new Set(DIRECT_WRITE_APPROVED.map((p) => path.normalize(p)));
   const writers = [];
@@ -515,13 +533,35 @@ export function listUnapprovedCanonicalWriters(rootDir = path.resolve('src/core'
       if (!entry.name.endsWith('.mjs')) continue;
       const relative = path.relative(process.cwd(), absolute).split(path.sep).join('/');
       if (approved.has(relative) || approved.has(path.normalize(relative))) continue;
-      const text = fs.readFileSync(absolute, 'utf8');
-      if (/\bwriteNode\s*\(/.test(text) || /\batomicWrite\s*\([^)]*\.md/.test(text)) {
-        writers.push(relative);
+
+      const lines = fs.readFileSync(absolute, 'utf8').split('\n');
+      const offenses = [];
+      for (let i = 0; i < lines.length; i += 1) {
+        if (!RAW_WRITE_CALL.test(lines[i])) continue;
+        // A call can wrap onto the next line; check the target on both.
+        const window = `${lines[i]}\n${lines[i + 1] || ''}`;
+        if (STAGING_TARGET.test(window)) continue;
+        if (!VAULT_TARGET.test(window)) continue;
+        // Waivers are per call site, never per file: a file allowlisted once
+        // for a legitimate reason silently absolves every raw write added to it
+        // later, which is how these bypasses stayed invisible.
+        //
+        // Only the comment block *immediately* above counts. A fixed look-back
+        // window has the same leak in miniature — one waived write would cover
+        // an unwaived one a line or two below it.
+        let waived = false;
+        for (let j = i - 1; j >= 0; j -= 1) {
+          const above = lines[j].trim();
+          if (!above.startsWith('//') && !above.startsWith('*') && !above.startsWith('/*')) break;
+          if (RAW_WRITE_WAIVER.test(above)) { waived = true; break; }
+        }
+        if (waived) continue;
+        offenses.push({ line: i + 1, source: lines[i].trim() });
       }
+      if (offenses.length) writers.push({ file: relative, offenses });
     }
   }
-  return writers.sort();
+  return writers.sort((a, b) => a.file.localeCompare(b.file));
 }
 
 export function resolveHostDefinition(type) {

package/src/core/task-envelope.mjs

@@ -201,6 +201,7 @@ export function persistEnvelope(envelope, queueDir) {
   for (const key of Object.keys(frontmatter)) {
     if (frontmatter[key] === undefined) delete frontmatter[key];
   }
+  // ssss-raw-write: scheduler/queue task envelope, not a vault node.
   atomicWrite(filepath, safeStringify(body || task.intent || '', frontmatter));
   task._filepath = filepath;
   return task;

package/src/core/validated-write.mjs

@@ -8,12 +8,13 @@
  */
 
 import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
 import { processOperationAsync } from './operation-validator.mjs';
-import { safeStringify } from './vault.mjs';
+import { safeStringify, isSafeVaultName } from './vault.mjs';
 import { invalidate } from './vault-cache.mjs';
 
-const SAFE_NAME = /^[a-zA-Z0-9_-]+$/;
-
 /**
  * Normalize a vault node so package universal frontmatter + TR memory v2 pass.
  */
@@ -107,10 +108,10 @@ function buildEnvelope(node, options = {}) {
   const prepared = prepareNodeForContract(node);
   const { body, _filePath, _layer, _filepath, ...frontmatter } = prepared;
 
-  if (!SAFE_NAME.test(String(frontmatter.slug))) {
+  if (!isSafeVaultName(frontmatter.slug)) {
     throw new Error(`Invalid slug: ${frontmatter.slug}`);
   }
-  if (!SAFE_NAME.test(String(frontmatter.category))) {
+  if (!isSafeVaultName(frontmatter.category)) {
     throw new Error(`Invalid category: ${frontmatter.category}`);
   }
 
@@ -166,3 +167,65 @@ export async function writeNodeValidatedAsync(node, vaultDir, options = {}) {
 export function validateNode(node, vaultDir) {
   return writeNodeValidatedAsync(node, vaultDir, { dryRun: true });
 }
+
+/**
+ * Resolve the vault root that owns a node file.
+ *
+ * Walks up looking for a `memory-vault` directory. Falls back to the
+ * grandparent (i.e. the parent of the category folder) so scoped roots and
+ * test fixtures that do not use the canonical name still work.
+ */
+export function resolveVaultDir(filePath) {
+  if (!filePath) return null;
+  let cur = path.dirname(path.resolve(filePath));
+  while (cur && cur !== path.dirname(cur)) {
+    if (path.basename(cur) === 'memory-vault') return cur;
+    cur = path.dirname(cur);
+  }
+  return path.dirname(path.dirname(path.resolve(filePath)));
+}
+
+/**
+ * Read a node off disk, mutate its frontmatter, and write it back through the
+ * Core Contract.
+ *
+ * Stampers (confidence decay, cutoff-risk flags, supersede markers, priority
+ * escalation) used to read → mutate → atomicWrite, which skipped validation
+ * entirely: a stamper could lower `confidence` below its floor or drop a
+ * required field and nothing would notice until a much later read failed.
+ *
+ * The on-disk location is preserved via an explicit path override. Without it
+ * the envelope would recompute `<category>/<slug>.md`, and any node whose
+ * folder is outside the closed memory-category enum (daily/, corrections/,
+ * queries/, system/) would be rewritten to a new location while the original
+ * was left behind as an orphan.
+ *
+ * @param {string} filePath  Absolute path to an existing node file
+ * @param {(data: object, body: string) => (object|void)} mutate
+ *        Mutates frontmatter in place, or returns `{ data, body }` to replace.
+ * @param {object} [options] Passed through to writeNodeValidatedAsync
+ * @returns {Promise<object>} Operation response, or `{ success: false }`
+ */
+export async function updateNodeInPlace(filePath, mutate, options = {}) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return { success: false, error: `Node file not found: ${filePath}` };
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const parsed = matter(raw);
+  const data = { ...parsed.data };
+  let body = parsed.content;
+
+  const replacement = mutate(data, body);
+  const nextData = replacement?.data || data;
+  if (replacement && typeof replacement.body === 'string') body = replacement.body;
+
+  const vaultDir = options.vaultDir || resolveVaultDir(filePath);
+  const relativePath = path.relative(vaultDir, path.resolve(filePath))
+    .split(path.sep).join('/');
+
+  return writeNodeValidatedAsync({ ...nextData, body }, vaultDir, {
+    ...options,
+    path: relativePath,
+  });
+}

package/src/core/vault-backfill.mjs

@@ -0,0 +1,259 @@
+/**
+ * Vault backfill — bring historical nodes up to the current SSSS contract.
+ *
+ * Most nodes in a long-lived vault predate the schema they are now validated
+ * against: SSSS 0.9 §4.2 made `description` and `timestamp` universally
+ * required, and for a long stretch nothing enforced it — several subsystems
+ * wrote nodes with raw filesystem writes that never reached the Core Contract.
+ *
+ * This walks every node, asks the contract what it would take to make it valid,
+ * and reports that. Applying is opt-in and takes a snapshot of the vault being
+ * changed first, because this rewrites the user's own memory at scale.
+ *
+ * Deliberately walks the filesystem rather than using getNodes(): getNodes()
+ * returns only `type: memory` documents, so proposals, migrations and every
+ * other vault primitive would be silently skipped by exactly the pass meant to
+ * repair them.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { prepareNodeForContract, validateNode, updateNodeInPlace } from './validated-write.mjs';
+import { createSnapshot } from './snapshot.mjs';
+import { logger } from './logger.mjs';
+
+// index.md / log.md are OKF bundle artifacts written alongside the nodes, not
+// nodes themselves — okf-adapter excludes them from its own walks too.
+const NON_NODE_FILES = new Set(['index.md', 'log.md']);
+
+// memory-vault/queries/ holds Obsidian Dataview dashboards (`type: query`,
+// no slug, no category, a ```dataview block for a body). They are saved views
+// over the vault, not entries in it — `query` is not an SSSS primitive and
+// never will be. Repairing them would mean inventing a slug and category for a
+// file that should not have either.
+const NON_NODE_DIRS = new Set(['queries']);
+
+export function walkVaultNodes(dir, acc = []) {
+  if (!fs.existsSync(dir)) return acc;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!entry.name.startsWith('.') && !NON_NODE_DIRS.has(entry.name)) walkVaultNodes(full, acc);
+    } else if (entry.name.endsWith('.md') && !NON_NODE_FILES.has(entry.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+
+/**
+ * Repair known-bad *shapes* left by writers that bypassed the contract.
+ *
+ * prepareNodeForContract only fills fields that are missing; it never rewrites
+ * a value that is present, which is the right default — but it means a field
+ * stored with the wrong type stays wrong forever. These are the specific
+ * corruptions found in the vault, each repaired so no information is lost:
+ * the old value is carried into the correct structure rather than replaced by
+ * a default.
+ *
+ * Anything not listed here is left alone. A node this cannot express is
+ * reported, never guessed at.
+ */
+export function normalizeLegacyShapes(data) {
+  const out = { ...data };
+  const repairs = [];
+
+  // repo-sync wrote `source` as "repo-sync:<repo>:<path>" (or a bare label) and
+  // `decay` as the number 0. Both are objects in MemoryNodeSchema.
+  if (typeof out.source === 'string') {
+    const raw = out.source;
+    const match = /^repo-sync:(.+?):(.+)$/.exec(raw);
+    out.source = match
+      ? { type: 'repo-sync', session_id: `${match[1]}:${match[2]}`, agent: 'repo-sync', evidence_count: 1 }
+      : { type: raw, session_id: raw, evidence_count: 1 };
+    repairs.push('source');
+  }
+
+  if (typeof out.decay === 'number') {
+    // The number was an access count in the old shape, never a half-life.
+    out.decay = { half_life_days: 365, access_count: out.decay };
+    repairs.push('decay');
+  }
+
+  // YAML parses an unquoted ISO timestamp into a Date. Most write paths
+  // stringify first; the ones that did not left Date objects on disk.
+  for (const key of ['timestamp', 'created', 'updated', 'last_accessed', 'x_temporal_context']) {
+    if (out[key] instanceof Date) {
+      out[key] = out[key].toISOString();
+      repairs.push(key);
+    }
+  }
+
+  if (Array.isArray(out.x_citations)) {
+    out.x_citations = out.x_citations.map((citation) => {
+      if (!citation || typeof citation !== 'object') return citation;
+      if (citation.published instanceof Date) {
+        repairs.push('x_citations.published');
+        return { ...citation, published: citation.published.toISOString() };
+      }
+      return citation;
+    });
+  }
+
+  return { data: out, repairs };
+}
+
+/**
+ * Field-level diff between a node as stored and as the contract would have it.
+ * Reports only additions and changes; nothing is ever dropped.
+ */
+export function diffNode(original) {
+  const prepared = prepareNodeForContract(normalizeLegacyShapes(original).data);
+  const added = {};
+  const changed = {};
+  for (const [key, value] of Object.entries(prepared)) {
+    if (key === 'body') continue;
+    if (!(key in original) || original[key] === undefined || original[key] === null) {
+      added[key] = value;
+    } else if (JSON.stringify(original[key]) !== JSON.stringify(value)) {
+      changed[key] = { from: original[key], to: value };
+    }
+  }
+  return { added, changed };
+}
+
+
+async function validate(data, body, vaultDir) {
+  try {
+    const result = await validateNode({ ...data, body }, vaultDir);
+    if (result.success) return { success: true, errors: [] };
+    return { success: false, errors: result.validation?.errors || [result.error || 'unknown'] };
+  } catch (err) {
+    // A slug or category outside the safe-name allowlist throws before the
+    // envelope is even built; that is a finding, not a crash.
+    return { success: false, errors: [err.message] };
+  }
+}
+
+/**
+ * Inspect a vault without writing anything.
+ *
+ * @returns {Promise<{vaultDir: string, total: number, valid: number,
+ *   invalid: number, unreadable: string[], fieldCounts: object,
+ *   errorCounts: object, nodes: object[]}>}
+ */
+export async function analyzeVault(vaultDir) {
+  const files = walkVaultNodes(vaultDir);
+  const report = {
+    vaultDir,
+    total: files.length,
+    valid: 0,
+    invalid: 0,
+    repairable: 0,
+    unfixable: [],
+    unreadable: [],
+    fieldCounts: {},
+    shapeRepairs: {},
+    errorCounts: {},
+    nodes: [],
+  };
+
+  for (const file of files) {
+    let parsed;
+    try {
+      parsed = matter(fs.readFileSync(file, 'utf8'));
+    } catch (err) {
+      report.unreadable.push(`${file}: ${err.message}`);
+      continue;
+    }
+
+    const original = parsed.data || {};
+
+    // Validate the node exactly as it sits on disk. Validating the repaired
+    // form here would report a clean vault while the files are still broken —
+    // and leave nothing for --apply to do.
+    const asStored = await validate(original, parsed.content, vaultDir);
+    if (asStored.success) {
+      report.valid += 1;
+      continue;
+    }
+
+    report.invalid += 1;
+    for (const err of asStored.errors) {
+      const key = String(err).split('\n')[0].slice(0, 120);
+      report.errorCounts[key] = (report.errorCounts[key] || 0) + 1;
+    }
+
+    // Would this run actually fix it? A node that still fails after repair is
+    // reported separately rather than counted as work in progress.
+    const { data: normalized, repairs } = normalizeLegacyShapes(original);
+    const afterRepair = await validate(normalized, parsed.content, vaultDir);
+    if (afterRepair.success) report.repairable += 1;
+    else {
+      report.unfixable.push({ file, errors: afterRepair.errors });
+      continue;
+    }
+
+    const { added, changed } = diffNode(original);
+    for (const key of Object.keys(added)) {
+      report.fieldCounts[key] = (report.fieldCounts[key] || 0) + 1;
+    }
+    for (const key of repairs) {
+      report.shapeRepairs[key] = (report.shapeRepairs[key] || 0) + 1;
+    }
+    report.nodes.push({ file, added, changed, repairs });
+  }
+
+  return report;
+}
+
+/**
+ * Repair a vault in place through the Core Contract.
+ *
+ * Takes a snapshot of *this* vault before the first write. Nodes that still
+ * fail after preparation are left exactly as they are and reported — a node the
+ * contract cannot express is a node a blind rewrite would corrupt.
+ */
+export async function backfillVault(vaultDir, options = {}) {
+  const { snapshot = true, limit = Infinity, onProgress } = options;
+  const analysis = await analyzeVault(vaultDir);
+
+  if (analysis.invalid === 0) {
+    return { ...analysis, snapshotId: null, repaired: 0, failed: [] };
+  }
+
+  let snapshotId = null;
+  if (snapshot) {
+    const snap = createSnapshot('pre-backfill', vaultDir);
+    if (!snap.success) {
+      throw new Error(`Refusing to backfill without a snapshot: ${snap.error}`);
+    }
+    snapshotId = snap.snapshot_id;
+    logger.info('vault-backfill', `Safety snapshot ${snapshotId} for ${vaultDir}`);
+  }
+
+  let repaired = 0;
+  const failed = [];
+  const targets = analysis.nodes.slice(0, limit);
+
+  for (const [index, target] of targets.entries()) {
+    try {
+      // prepareNodeForContract inside the write path supplies missing fields;
+      // the normalizer repairs fields stored with the wrong type. Neither
+      // invents content — both preserve what the old value carried.
+      const result = await updateNodeInPlace(target.file, (data) => {
+        const { data: normalized } = normalizeLegacyShapes(data);
+        for (const key of Object.keys(normalized)) data[key] = normalized[key];
+      }, { vaultDir });
+      if (result.success) repaired += 1;
+      else failed.push({ file: target.file, errors: result.validation?.errors || [result.error] });
+    } catch (err) {
+      failed.push({ file: target.file, errors: [err.message] });
+    }
+    if (onProgress && index % 100 === 0) onProgress(index + 1, targets.length);
+  }
+
+  return { ...analysis, snapshotId, repaired, failed };
+}