wendkeep 0.57.2 → 0.58.0

package/hooks/vault-health.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
 import {
@@ -11,6 +11,9 @@ import {
   wikilinkFromRel,
 } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
+import { parseSharedMemory, validateMemoryEvent } from './memory-schema.mjs';
+import { reduceMemoryEvents } from './memory-store.mjs';
+import { validateMemoryBundle } from '../src/validate-memory.mjs';
 
 const DEFAULT_PENDING_PATTERNS = [
   /^- \[ \] Revisar resumo da sessão$/i,
@@ -93,6 +96,124 @@ function linkedNotesFromSession(content) {
   return notes;
 }
 
+const MEMORY_STATUS_COMMAND = 'wendkeep memory status --gate --vault <vault>';
+const MEMORY_REPAIR_COMMAND = 'wendkeep memory repair --vault <vault>';
+
+function readJsonLines(path, label) {
+  if (!existsSync(path)) return { items: [], errors: [] };
+  const raw = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
+  const lines = raw.endsWith('\n') ? raw.split('\n').slice(0, -1) : raw.split('\n');
+  const items = [];
+  const errors = [];
+  lines.forEach((line, index) => {
+    if (!line.trim()) {
+      if (raw) errors.push(`${label} linha ${index + 1} está vazia.`);
+      return;
+    }
+    try { items.push(JSON.parse(line)); }
+    catch (error) { errors.push(`${label} linha ${index + 1} contém JSON inválido/parcial: ${error.message}`); }
+  });
+  return { items, errors };
+}
+
+function inspectOutbox(vaultBase, projectId) {
+  const dir = join(vaultBase, '.brain', 'memory-outbox');
+  if (!existsSync(dir)) return { count: 0, errors: [] };
+  const files = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
+  const errors = [];
+  for (const name of files) {
+    const path = join(dir, name);
+    try {
+      const event = JSON.parse(readFileSync(path, 'utf8'));
+      const validation = validateMemoryEvent(event, projectId ? { projectId } : {});
+      if (!validation.ok) errors.push(`${name}: ${validation.errors.join(' ')}`);
+    } catch (error) {
+      errors.push(`${name}: JSON inválido: ${error.message}`);
+    }
+  }
+  return { count: files.length, errors };
+}
+
+/**
+ * Read-only consistency check for the local memory-v2 bundle. It intentionally
+ * does not acquire MEMORY.lock or invoke the projector/repair paths.
+ */
+export function checkMemoryBundle(vaultBase) {
+  const brain = join(vaultBase, '.brain');
+  const bundle = validateMemoryBundle(vaultBase);
+  const failures = [];
+  const warnings = [];
+  const parsedShared = typeof bundle.shared?.content === 'string'
+    ? parseSharedMemory(bundle.shared.content)
+    : { metadata: {} };
+  const metadata = parsedShared.metadata || {};
+  const outbox = inspectOutbox(vaultBase, bundle.project?.projectId);
+  const candidates = readJsonLines(join(brain, 'MEMORY_CANDIDATES.jsonl'), 'MEMORY_CANDIDATES.jsonl');
+
+  const ledgerCorrupt = (bundle.ledger?.errors || []).length > 0;
+  if (ledgerCorrupt) {
+    for (const error of bundle.ledger.errors) {
+      failures.push(`${error} Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+    }
+  }
+  for (const error of bundle.errors || []) {
+    if (error.startsWith('ledger:')) continue;
+    failures.push(`${error} Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+  }
+
+  if (outbox.errors.length) {
+    failures.push(`Outbox corrompida (${outbox.errors.join('; ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+  }
+  if (candidates.errors.length) {
+    failures.push(`${candidates.errors.join('; ')} Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+  }
+
+  let replay = null;
+  if (bundle.ledger?.ok) {
+    try { replay = reduceMemoryEvents(bundle.ledger.events); }
+    catch (error) {
+      failures.push(`Ledger não pode ser reduzido: ${error.message}. Execute com segurança: ${MEMORY_REPAIR_COMMAND}.`);
+    }
+  }
+  if (replay && bundle.shared?.ok) {
+    const divergences = [];
+    if (metadata.revision !== replay.revision) divergences.push(`revision ${metadata.revision} != ${replay.revision}`);
+    if (metadata.event_cursor !== replay.eventCursor) divergences.push(`event_cursor ${metadata.event_cursor} != ${replay.eventCursor}`);
+    if (metadata.state_hash !== replay.stateHash) divergences.push(`state_hash ${metadata.state_hash} != ${replay.stateHash}`);
+    if (divergences.length) {
+      failures.push(`Projeção SHARED stale/lag (${divergences.join('; ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+    }
+  }
+
+  const unresolved = candidates.items.filter((item) => !['resolved', 'rejected', 'superseded'].includes(item?.status));
+  const activeConflicts = unresolved.filter((item) => item?.reason === 'conflict');
+  const ordinaryCandidates = unresolved.filter((item) => item?.reason !== 'conflict');
+  if (activeConflicts.length) {
+    failures.push(`${activeConflicts.length} conflito ativo em chave operacional (${activeConflicts.map((item) => item.memory_key || item.candidate_id).join(', ')}). Inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+  }
+  if (outbox.count) warnings.push(`${outbox.count} evento(s) pendente(s) na outbox; execute o projector quando seguro.`);
+  if (ordinaryCandidates.length) warnings.push(`${ordinaryCandidates.length} candidate(s) aguardando curadoria humana.`);
+  for (const warning of bundle.warnings || []) warnings.push(warning);
+
+  const ok = failures.length === 0;
+  return {
+    ok,
+    status: ok ? (warnings.length ? 'warning' : 'healthy') : 'blocked',
+    failures,
+    warnings,
+    metrics: {
+      schemaVersion: metadata.schema_version ?? null,
+      revision: metadata.revision ?? null,
+      eventCursor: metadata.event_cursor ?? null,
+      stateHash: metadata.state_hash ?? null,
+      ledgerEvents: bundle.ledger?.events?.length || 0,
+      pendingOutbox: outbox.count,
+      candidates: candidates.items.length,
+      activeConflicts: activeConflicts.length,
+    },
+  };
+}
+
 function checkSession({ vaultBase, sessionRel, control, registry }) {
   const failures = [];
   const warnings = [];
@@ -181,6 +302,21 @@ export function runVaultHealth({ vaultBase, session = '' }) {
     return total + (existsSync(dir) ? listMarkdownFiles(dir).length : 0);
   }, 0);
 
+  const memoryMarkers = [
+    join(vaultBase, '.brain', 'SHARED_MEMORY.md'),
+    join(vaultBase, '.brain', 'MEMORY_EVENTS.jsonl'),
+    join(vaultBase, '.brain', 'MEMORY_CANDIDATES.jsonl'),
+    join(vaultBase, '.brain', 'memory-outbox'),
+  ];
+  let memory = { status: 'legacy', metrics: {} };
+  if (memoryMarkers.some((path) => existsSync(path))) {
+    memory = checkMemoryBundle(vaultBase);
+    failures.push(...memory.failures.map((item) => `Memória: ${item}`));
+    warnings.push(...memory.warnings.map((item) => `Memória: ${item}`));
+  } else {
+    warnings.push(`Bundle de memória v2 ausente (vault legado); inspecione com: ${MEMORY_STATUS_COMMAND}.`);
+  }
+
   return {
     ok: failures.length === 0,
     session: sessionRel,
@@ -190,7 +326,9 @@ export function runVaultHealth({ vaultBase, session = '' }) {
       ...sessionResult.metrics,
       registrySessions: Object.keys(registry.sessions || {}).length,
       derivedNotes: derivedCount,
+      memory: memory.metrics,
     },
+    memoryStatus: memory.status,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.57.2",
+  "version": "0.58.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {
@@ -49,6 +49,6 @@
     "url": "https://github.com/rogersialves/wendkeep/issues"
   },
   "devDependencies": {
-    "wendkeep": "^0.57.1"
+    "wendkeep": "^0.57.2"
   }
 }

package/src/init.mjs

@@ -39,6 +39,7 @@ import { LOCALES, DEFAULT_LOCALE, getLocale, clearLocaleCache, vaultFolders } fr
 import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
 import { adoptSpecsState, ensureSpecsReadme, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
 import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
+import { seedMemoryV2 } from './memory.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -506,6 +507,7 @@ export async function runInit(argv) {
   if (!existsSync(corePath)) writeFileSync(corePath, renderCoreSkeleton(loc.id), 'utf8');
   const protoPath = join(brainDir, 'COMPACTION_PROTOCOL.md');
   if (!existsSync(protoPath)) writeFileSync(protoPath, renderCompactionProtocol(), 'utf8');
+  seedMemoryV2(vaultPath);
   // Seed the definitions layer (.brain/agents + .brain/skills): versioned source of
   // truth for custom agents/skills. `wendkeep sync-defs` copies them to the agent dirs.
   seedDefinitions(brainDir);

package/src/memory.mjs

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { sanitizeMemoryText, renderSharedMemory, validateSharedMemory } from '../hooks/memory-schema.mjs';
+import {
+  enqueueMemoryEvent, projectMemoryOutbox, repairMemoryLedger,
+} from '../hooks/memory-store.mjs';
+import { writeFileAtomic } from '../hooks/session-note-io.mjs';
+import { validateMemoryBundle } from './validate-memory.mjs';
+import { checkMemoryBundle } from '../hooks/vault-health.mjs';
+
+const BRAIN = '.brain';
+const LEDGER = 'MEMORY_EVENTS.jsonl';
+const SHARED = 'SHARED_MEMORY.md';
+const CANDIDATES = 'MEMORY_CANDIDATES.jsonl';
+
+function brainPath(vault, name) { return join(vault, BRAIN, name); }
+function hash(value) { return createHash('sha256').update(String(value)).digest('hex'); }
+
+function projectId(vault) {
+  const marker = JSON.parse(readFileSync(brainPath(vault, 'PROJECT.json'), 'utf8'));
+  if (!marker?.projectId) throw new Error('PROJECT.json inválido: projectId ausente.');
+  return marker.projectId;
+}
+
+function legacyCandidates(content) {
+  const safe = sanitizeMemoryText(content).replace(/\r\n/g, '\n');
+  const candidates = [];
+  let section = 'Legacy';
+  for (const line of safe.split('\n')) {
+    const heading = line.match(/^#{1,3}\s+(.+)/);
+    if (heading) { section = heading[1].trim(); continue; }
+    const value = line.replace(/^[-*]\s+/, '').trim();
+    if (!value) continue;
+    const candidateId = `legacy-${hash(`${section}\0${value}`).slice(0, 16)}`;
+    candidates.push({
+      v: 1,
+      candidate_id: candidateId,
+      reason: 'legacy_shared',
+      memory_key: `legacy.${hash(section).slice(0, 8)}.${candidates.length + 1}`,
+      value,
+      section: sanitizeMemoryText(section),
+      source: 'SHARED_MEMORY.md',
+    });
+  }
+  return candidates;
+}
+
+function candidateText(candidates) {
+  return candidates.map((item) => `${JSON.stringify(item)}\n`).join('');
+}
+
+export function seedMemoryV2(vault) {
+  const brain = join(vault, BRAIN);
+  mkdirSync(brain, { recursive: true });
+  const created = [];
+  const artifacts = [
+    [LEDGER, ''],
+    [CANDIDATES, ''],
+    [SHARED, renderSharedMemory()],
+  ];
+  for (const [name, content] of artifacts) {
+    const path = join(brain, name);
+    if (!existsSync(path)) {
+      writeFileSync(path, content, 'utf8');
+      created.push(name);
+    }
+  }
+  return { status: created.length ? 'seeded' : 'unchanged', created };
+}
+
+export function memoryStatus(vault) {
+  return checkMemoryBundle(vault);
+}
+
+export function migrateMemory(vault, { apply = false, validateBundle = validateMemoryBundle } = {}) {
+  projectId(vault);
+  const sharedPath = brainPath(vault, SHARED);
+  const hadShared = existsSync(sharedPath);
+  const legacy = hadShared ? readFileSync(sharedPath, 'utf8') : '';
+  const parsed = validateSharedMemory(legacy);
+  const alreadyV2 = parsed.ok && parsed.metadata.schema_version === 2;
+  const candidates = alreadyV2 ? [] : legacyCandidates(legacy);
+  const backupPath = hadShared ? `${sharedPath}.legacy-${hash(legacy).slice(0, 12)}.bak` : null;
+  if (!apply) return { status: 'dry-run', alreadyV2, candidates: candidates.length, backupPath };
+  if (alreadyV2) {
+    seedMemoryV2(vault);
+    return { status: 'unchanged', alreadyV2: true, candidates: 0, backupPath: null };
+  }
+
+  // Validate every generated byte before the first publication. CORE is never written.
+  const emptyShared = renderSharedMemory();
+  const sharedValidation = validateSharedMemory(emptyShared, { eventIds: new Set() });
+  if (!sharedValidation.ok) throw new Error(`Migração inválida: ${sharedValidation.errors.join(' ')}`);
+  if (backupPath && !existsSync(backupPath)) copyFileSync(sharedPath, backupPath);
+  const targets = [LEDGER, SHARED, CANDIDATES].map((name) => brainPath(vault, name));
+  const before = new Map(targets.map((path) => [path, {
+    existed: existsSync(path),
+    content: existsSync(path) ? readFileSync(path, 'utf8') : '',
+  }]));
+  try {
+    if (!existsSync(brainPath(vault, LEDGER))) writeFileAtomic(brainPath(vault, LEDGER), '');
+    writeFileAtomic(sharedPath, emptyShared);
+    writeFileAtomic(brainPath(vault, CANDIDATES), candidateText(candidates));
+    const validation = validateBundle(vault);
+    if (!validation.ok) throw new Error(`Bundle migrado inválido: ${validation.errors.join(' ')}`);
+    return { status: 'migrated', alreadyV2: false, candidates: candidates.length, backupPath, validation };
+  } catch (error) {
+    for (const [path, snapshot] of before) {
+      if (snapshot.existed) writeFileAtomic(path, snapshot.content);
+      else if (existsSync(path)) unlinkSync(path);
+    }
+    throw error;
+  }
+}
+
+function readCandidates(vault) {
+  const path = brainPath(vault, CANDIDATES);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
+}
+
+export function decideMemoryCandidate(vault, { action, candidateId, value } = {}) {
+  if (!['promote', 'reject'].includes(action)) throw new TypeError('action deve ser promote ou reject.');
+  if (!candidateId) throw new TypeError('candidateId é obrigatório.');
+  const candidates = readCandidates(vault);
+  const candidate = candidates.find((item) => item.candidate_id === candidateId);
+  if (!candidate) throw new Error(`Candidate não encontrado: ${candidateId}`);
+  const now = new Date().toISOString();
+  const event = {
+    v: 1,
+    event_id: `cli-${action}-${hash(candidateId).slice(0, 20)}`,
+    project_id: projectId(vault),
+    memory_key: action === 'promote' ? candidate.memory_key : `candidate.rejected.${candidateId}`,
+    operation: 'assert',
+    value: sanitizeMemoryText(action === 'promote' ? (value ?? candidate.value ?? candidate.values?.[0] ?? '') : 'rejected'),
+    authority: 'verified',
+    activation_id: 'wendkeep-memory-cli',
+    turn_sequence: 0,
+    observed_at: now,
+    evidence: [`candidate:${candidateId}`],
+  };
+  enqueueMemoryEvent(vault, event);
+  const projection = projectMemoryOutbox(vault);
+  if (projection.status === 'busy') return { status: 'busy', candidateId };
+  const remaining = candidates.filter((item) => item.candidate_id !== candidateId);
+  const projected = readCandidates(vault);
+  const merged = new Map([...remaining, ...projected].map((item) => [item.candidate_id, item]));
+  writeFileAtomic(brainPath(vault, CANDIDATES), candidateText([...merged.values()]));
+  return { status: action === 'promote' ? 'promoted' : 'rejected', candidateId, eventId: event.event_id, projection };
+}
+
+export function repairMemory(vault) {
+  const repaired = repairMemoryLedger(vault);
+  if (repaired.status === 'busy') return repaired;
+  const projection = projectMemoryOutbox(vault);
+  return { status: projection.status === 'busy' ? 'busy' : 'repaired', repaired, projection };
+}
+
+export function runValidateMemoryBundle(argv) {
+  const vault = option(argv, '--vault');
+  if (!vault) {
+    process.stderr.write('wendkeep validate-memory: --vault requer um path.\n');
+    process.exitCode = 2;
+    return;
+  }
+  if (!existsSync(vault)) {
+    process.stderr.write(`wendkeep validate-memory: not found: ${vault}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  const result = validateMemoryBundle(vault);
+  if (!result.ok) {
+    process.stderr.write(`❌  bundle de memória inválido (${result.errors.length} erro(s)):\n`);
+    for (const error of result.errors) process.stderr.write(`   - ${error}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write('✅  bundle de memória v2 OK (CORE + ledger + SHARED).\n');
+  process.exitCode = 0;
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+export function runMemory(argv) {
+  const [sub, positional] = argv;
+  const vault = option(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vault) { process.stderr.write('wendkeep memory: passe --vault <path>.\n'); process.exitCode = 2; return; }
+  try {
+    let result;
+    if (sub === 'status') result = memoryStatus(vault);
+    else if (sub === 'migrate') result = migrateMemory(vault, { apply: argv.includes('--apply') });
+    else if (sub === 'repair') result = repairMemory(vault);
+    else if (sub === 'promote' || sub === 'reject') result = decideMemoryCandidate(vault, { action: sub, candidateId: positional });
+    else { process.stderr.write('wendkeep memory: use status | migrate [--apply] | repair | promote <candidate> | reject <candidate>.\n'); process.exitCode = 2; return; }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exitCode = sub === 'status' && argv.includes('--gate')
+      ? (result.status === 'blocked' ? 1 : 0)
+      : (result.ok === false ? 1 : 0);
+  } catch (error) {
+    process.stderr.write(`wendkeep memory: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/taxonomy.mjs

@@ -34,6 +34,9 @@ export const HOOK_FILES = [
   'subagent-usage.mjs',
   'pricing.json',
   'brain-core.mjs',
+  'memory-schema.mjs',
+  'memory-store.mjs',
+  'memory-handoff.mjs',
   'change-core.mjs',
   'spec-core.mjs',
   'sensors-core.mjs',

package/src/validate-memory.mjs

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateMemoryEvent, validateSharedMemory } from '../hooks/memory-schema.mjs';
+import { validateCore } from './validate-core.mjs';
+
+function failedComponent(errors, extra = {}) {
+  return { ok: false, errors: Array.isArray(errors) ? errors : [errors], warnings: [], ...extra };
+}
+
+function readRequired(path, label) {
+  if (!existsSync(path)) return { ok: false, error: `${label} ausente: ${path}` };
+  try {
+    return { ok: true, content: readFileSync(path, 'utf8') };
+  } catch (error) {
+    return { ok: false, error: `${label} ilegível: ${error?.message || error}` };
+  }
+}
+
+export function readProjectForValidation(vaultBase) {
+  const path = join(vaultBase, '.brain', 'PROJECT.json');
+  const read = readRequired(path, 'PROJECT.json');
+  if (!read.ok) return failedComponent(read.error, { projectId: '', path });
+  try {
+    const marker = JSON.parse(read.content);
+    if (!marker || typeof marker.projectId !== 'string' || !marker.projectId) {
+      return failedComponent('PROJECT.json inválido: projectId ausente.', { projectId: '', path });
+    }
+    return { ok: true, errors: [], warnings: [], projectId: marker.projectId, marker, path };
+  } catch (error) {
+    return failedComponent(`PROJECT.json contém JSON inválido: ${error?.message || error}`, { projectId: '', path });
+  }
+}
+
+/** Read and validate the append-only JSONL authority without repairing or mutating it. */
+export function readLedgerForValidation(vaultBase, { projectId } = {}) {
+  const path = join(vaultBase, '.brain', 'MEMORY_EVENTS.jsonl');
+  const read = readRequired(path, 'MEMORY_EVENTS.jsonl');
+  if (!read.ok) return failedComponent(read.error, { events: [], eventIds: new Set(), path });
+
+  const errors = [];
+  const warnings = [];
+  const events = [];
+  const eventIds = new Set();
+  const normalized = read.content.replace(/\r\n/g, '\n');
+  const lines = normalized.split('\n');
+  const logicalLines = normalized === '' ? [] : (normalized.endsWith('\n') ? lines.slice(0, -1) : lines);
+  logicalLines.forEach((line, index) => {
+    if (!line.trim()) {
+      errors.push(`MEMORY_EVENTS.jsonl linha ${index + 1} está vazia no meio do ledger.`);
+      return;
+    }
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch (error) {
+      errors.push(`MEMORY_EVENTS.jsonl linha ${index + 1} contém JSON inválido/parcial: ${error?.message || error}`);
+      return;
+    }
+    const validation = validateMemoryEvent(event, projectId ? { projectId } : {});
+    for (const error of validation.errors) errors.push(`MEMORY_EVENTS.jsonl linha ${index + 1}: ${error}`);
+    for (const warning of validation.warnings) warnings.push(`MEMORY_EVENTS.jsonl linha ${index + 1}: ${warning}`);
+    if (typeof event?.event_id === 'string' && event.event_id) {
+      if (eventIds.has(event.event_id)) errors.push(`MEMORY_EVENTS.jsonl event_id duplicado: ${event.event_id}.`);
+      eventIds.add(event.event_id);
+    }
+    events.push(event);
+  });
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    events,
+    eventIds,
+    lineCount: logicalLines.length,
+    path,
+  };
+}
+
+function validateCoreArtifact(vaultBase) {
+  const path = join(vaultBase, '.brain', 'CORE.md');
+  const read = readRequired(path, 'CORE.md');
+  if (!read.ok) return failedComponent(read.error, { lineCount: 0, path });
+  return { ...validateCore(read.content), path, content: read.content };
+}
+
+function validateSharedArtifact(vaultBase, eventIds) {
+  const path = join(vaultBase, '.brain', 'SHARED_MEMORY.md');
+  const read = readRequired(path, 'SHARED_MEMORY.md');
+  if (!read.ok) return failedComponent(read.error, { path });
+  return { ...validateSharedMemory(read.content, { eventIds }), path, content: read.content };
+}
+
+export function combineMemoryResults({ project, core, ledger, shared }) {
+  const components = { project, core, ledger, shared };
+  const errors = [];
+  const warnings = [];
+  for (const [name, result] of Object.entries(components)) {
+    for (const error of result?.errors || []) errors.push(`${name}: ${error}`);
+    for (const warning of result?.warnings || []) warnings.push(`${name}: ${warning}`);
+  }
+  return { ok: errors.length === 0, errors, warnings, ...components };
+}
+
+/**
+ * Validate the v2 local memory bundle as a read-only composition. Missing/corrupt
+ * artifacts remain explicit failures; they are never silently treated as empty.
+ */
+export function validateMemoryBundle(vaultBase) {
+  const project = readProjectForValidation(vaultBase);
+  const core = validateCoreArtifact(vaultBase);
+  const ledger = readLedgerForValidation(vaultBase, { projectId: project.projectId });
+  const shared = validateSharedArtifact(vaultBase, ledger.eventIds);
+  return combineMemoryResults({ project, core, ledger, shared });
+}