wendkeep 0.59.0 → 0.61.0

package/packages/vault/src/project-vault.mjs

@@ -0,0 +1,327 @@
+// Keep Core: project-to-Vault binding and resolution, independent from Harness policy.
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+
+export const PROJECT_CONFIG_FILE = '.wendkeep.json';
+export const PROJECT_MARKER_REL = '.brain/PROJECT.json';
+export const PROJECT_CONFIG_SCHEMA = 1;
+
+const PROJECT_VAULT_INTEGRITY_CODES = new Set([
+  'WENDKEEP_VAULT_CONFIG_INVALID',
+  'WENDKEEP_VAULT_MARKER_MISSING',
+  'WENDKEEP_VAULT_PROJECT_MISMATCH',
+]);
+
+export function isProjectVaultIntegrityError(error) {
+  return PROJECT_VAULT_INTEGRITY_CODES.has(error?.code);
+}
+
+function json(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) {
+    const wrapped = new Error(`Configuração WendKeep inválida em "${path}": ${error.message}`);
+    wrapped.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw wrapped;
+  }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === content) return false;
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, content, 'utf8');
+  renameSync(temp, path);
+  return true;
+}
+
+function startDirectory(value) {
+  const candidate = resolve(String(value || process.cwd()));
+  try { return statSync(candidate).isFile() ? dirname(candidate) : candidate; }
+  catch { return candidate; }
+}
+
+function walkParents(start) {
+  const result = [];
+  let current = startDirectory(start);
+  const root = parse(current).root;
+  while (true) {
+    result.push(current);
+    if (current === root) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return result;
+}
+
+function inputStart(input = {}, fallback = '') {
+  return input.cwd
+    || input.project_dir
+    || input.projectDir
+    || input.workspace?.cwd
+    || process.env.CLAUDE_PROJECT_DIR
+    || fallback
+    || process.cwd();
+}
+
+function bindingDiagnostic(error) {
+  return {
+    code: error?.code || 'WENDKEEP_VAULT_CONFIG_INVALID',
+    message: error?.message || 'Configuração WendKeep inválida.',
+  };
+}
+
+function vaultFromConfig(projectRoot, config) {
+  const valid = config
+    && typeof config === 'object'
+    && !Array.isArray(config)
+    && config.schemaVersion === PROJECT_CONFIG_SCHEMA
+    && typeof config.projectId === 'string'
+    && config.projectId.trim()
+    && typeof config.vault === 'string'
+    && config.vault.trim();
+  if (!valid) {
+    const error = new Error(
+      `Configuração incompleta em "${join(projectRoot, PROJECT_CONFIG_FILE)}". `
+      + 'Rode `wendkeep init --project <path> --vault <path>`.',
+    );
+    error.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw error;
+  }
+  return isAbsolute(config.vault) ? resolve(config.vault) : resolve(projectRoot, config.vault);
+}
+
+export function readProjectBinding(projectRoot) {
+  const root = resolve(projectRoot);
+  const path = join(root, PROJECT_CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  const config = json(path);
+  return { config, configPath: path, projectRoot: root, base: vaultFromConfig(root, config) };
+}
+
+export function findProjectBinding(start) {
+  for (const projectRoot of walkParents(start)) {
+    const found = readProjectBinding(projectRoot);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function findLegacyProjectVault(start) {
+  for (const projectRoot of walkParents(start)) {
+    const settingsPath = join(projectRoot, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) continue;
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const raw = settings?.env?.OBSIDIAN_VAULT_PATH;
+      if (typeof raw === 'string' && raw.trim()) {
+        return {
+          base: isAbsolute(raw) ? resolve(raw) : resolve(projectRoot, raw),
+          projectRoot,
+          source: 'legacy-project-settings',
+          configPath: settingsPath,
+          projectId: '',
+          config: null,
+        };
+      }
+    } catch (error) {
+      const wrapped = new Error(`Configuração WendKeep legada inválida em "${settingsPath}": ${error.message}`);
+      wrapped.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+      throw wrapped;
+    }
+  }
+  return null;
+}
+
+export function readVaultMarker(vaultPath) {
+  const markerPath = join(resolve(vaultPath), ...PROJECT_MARKER_REL.split('/'));
+  if (!existsSync(markerPath)) return null;
+  return { marker: json(markerPath), markerPath };
+}
+
+function validateMarker(result) {
+  const found = readVaultMarker(result.base);
+  if (!found) {
+    const error = new Error(
+      `O vault "${result.base}" ainda não possui ${PROJECT_MARKER_REL}. `
+      + `Rode \`wendkeep init --project "${result.projectRoot}" --vault "${result.base}" --yes\`.`,
+    );
+    error.code = 'WENDKEEP_VAULT_MARKER_MISSING';
+    throw error;
+  }
+  if (found.marker?.projectId !== result.projectId) {
+    const error = new Error(
+      `Vault de outro projeto: configuração "${result.projectId}" aponta para marcador `
+      + `"${found.marker?.projectId || 'ausente'}" em "${found.markerPath}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+}
+
+export function resolveProjectVault({
+  input = {},
+  startDir = '',
+  explicitVault = '',
+  allowLegacySettings = true,
+  validateIdentity = true,
+} = {}) {
+  const start = inputStart(input, startDir);
+  const explicit = explicitVault || input?.obsidian_vault_path;
+  if (explicit) {
+    let bindingError = null;
+    try { findProjectBinding(start); }
+    catch (error) {
+      if (error?.code !== 'WENDKEEP_VAULT_CONFIG_INVALID') throw error;
+      bindingError = bindingDiagnostic(error);
+    }
+    return {
+      base: isAbsolute(explicit) ? resolve(explicit) : resolve(startDirectory(start), explicit),
+      source: explicitVault ? 'explicit' : 'payload',
+      projectRoot: startDirectory(start),
+      projectId: '',
+      configPath: '',
+      config: null,
+      ...(bindingError ? { bindingError } : {}),
+    };
+  }
+
+  let binding = null;
+  let bindingFailure = null;
+  try { binding = findProjectBinding(start); }
+  catch (error) {
+    if (error?.code !== 'WENDKEEP_VAULT_CONFIG_INVALID') throw error;
+    bindingFailure = error;
+  }
+  if (binding) {
+    const result = {
+      base: binding.base,
+      source: 'project-config',
+      projectRoot: binding.projectRoot,
+      projectId: binding.config.projectId,
+      configPath: binding.configPath,
+      config: binding.config,
+    };
+    if (validateIdentity) validateMarker(result);
+    return result;
+  }
+
+  if (allowLegacySettings) {
+    const legacy = findLegacyProjectVault(start);
+    if (legacy) {
+      return {
+        ...legacy,
+        ...(bindingFailure ? { bindingError: bindingDiagnostic(bindingFailure) } : {}),
+      };
+    }
+  }
+
+  if (bindingFailure) throw bindingFailure;
+
+  const error = new Error(
+    `Nenhum vault WendKeep vinculado ao projeto em "${startDirectory(start)}". `
+    + `Crie ${PROJECT_CONFIG_FILE} com \`wendkeep init --project "${startDirectory(start)}" --vault <path> --yes\`.`,
+  );
+  error.code = 'WENDKEEP_VAULT_UNCONFIGURED';
+  throw error;
+}
+
+function portableVaultPath(projectRoot, vaultPath) {
+  const rel = relative(projectRoot, vaultPath);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replaceAll('\\', '/');
+  return vaultPath;
+}
+
+function objectRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function bindProjectVault({ projectRoot, vaultPath, configPatch = {} }) {
+  const root = resolve(projectRoot);
+  const base = isAbsolute(vaultPath) ? resolve(vaultPath) : resolve(root, vaultPath);
+  const existing = readProjectBinding(root);
+  const existingMarker = readVaultMarker(base);
+  const projectId = existing?.config?.projectId || existingMarker?.marker?.projectId || randomUUID();
+
+  if (existingMarker?.marker?.projectId && existingMarker.marker.projectId !== projectId) {
+    const error = new Error(
+      `Não é seguro vincular "${root}" ao vault de outro projeto: `
+      + `esperado "${projectId}", encontrado "${existingMarker.marker.projectId}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+
+  mkdirSync(join(base, '.brain'), { recursive: true });
+  const previousConfig = objectRecord(existing?.config);
+  const patch = objectRecord(configPatch);
+  const config = {
+    ...previousConfig,
+    ...patch,
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    vault: portableVaultPath(root, base),
+  };
+  if (previousConfig.harness || patch.harness) {
+    config.harness = {
+      ...objectRecord(previousConfig.harness),
+      ...objectRecord(patch.harness),
+    };
+  }
+  const marker = {
+    ...objectRecord(existingMarker?.marker),
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    projectName: basename(root),
+  };
+  atomicJson(join(base, ...PROJECT_MARKER_REL.split('/')), marker);
+  atomicJson(join(root, PROJECT_CONFIG_FILE), config);
+  return { base, projectRoot: root, projectId, config, marker };
+}
+
+export function updateProjectBinding(projectRoot, updater) {
+  const binding = readProjectBinding(projectRoot);
+  if (!binding) {
+    const error = new Error(
+      `Nenhum binding WendKeep em "${resolve(projectRoot)}". Rode \`wendkeep init\` primeiro.`,
+    );
+    error.code = 'WENDKEEP_VAULT_UNCONFIGURED';
+    throw error;
+  }
+  if (typeof updater !== 'function') {
+    throw new TypeError('updateProjectBinding exige uma função updater.');
+  }
+
+  const current = {
+    ...binding.config,
+    ...(binding.config.harness ? { harness: { ...objectRecord(binding.config.harness) } } : {}),
+  };
+  const candidate = updater(current);
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    const error = new Error('Updater do binding WendKeep deve retornar um objeto de configuração.');
+    error.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw error;
+  }
+
+  const config = {
+    ...candidate,
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId: binding.config.projectId,
+    vault: binding.config.vault,
+  };
+  atomicJson(binding.configPath, config);
+  return {
+    ...binding,
+    config,
+    base: vaultFromConfig(binding.projectRoot, config),
+  };
+}

package/packages/vault/src/validate-core.mjs

@@ -0,0 +1,181 @@
+// Memory-compaction protocol for the curated .brain/CORE.md layer.
+// Ported from NutriGym-Vision's scripts/validate-brain-core.js to ESM:
+//   - cap 25 lines (hard), 22 (soft warning) — 1 durable item per line
+//   - 3 required sections
+//   - no secrets / no real-provider PII emails
+// Plus the seeded skeleton and the protocol reference doc.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const HARD_LIMIT = 25;
+const SOFT_LIMIT = 22;
+
+// Bilingual (0.8.0): a CORE is valid when it carries the COMPLETE section set of either
+// locale — pt-BR or en. Mixed/partial sets fail (the 3 sections are one contract).
+const SECTION_SETS = {
+  'pt-BR': [
+    { label: 'Preferências do Usuário', regex: /^##\s+Prefer[êe]ncias\s+do\s+Usu[áa]rio\s*$/im },
+    { label: 'Padrões Ativos', regex: /^##\s+Padr[õo]es\s+Ativos\s*$/im },
+    { label: 'Pendências Abertas', regex: /^##\s+Pend[êe]ncias\s+Abertas\s*$/im },
+  ],
+  en: [
+    { label: 'User Preferences', regex: /^##\s+User\s+Preferences\s*$/im },
+    { label: 'Active Patterns', regex: /^##\s+Active\s+Patterns\s*$/im },
+    { label: 'Open Items', regex: /^##\s+Open\s+Items\s*$/im },
+  ],
+};
+
+// Secret patterns reject only "real" values (length floor); abstract mentions like
+// `sk_*` / `whsec_*` (trailing asterisk) are allowed.
+const SECRET_PATTERNS = [
+  { name: 'Stripe secret key', regex: /\bsk_(?:live|test)_[A-Za-z0-9]{20,}\b/ },
+  { name: 'Stripe webhook secret', regex: /\bwhsec_[A-Za-z0-9]{20,}\b/ },
+  { name: 'JWT token', regex: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+  { name: 'Bearer token', regex: /\bBearer\s+[A-Za-z0-9._-]{20,}\b/i },
+  { name: 'OpenAI API key', regex: /\bsk-[A-Za-z0-9]{40,}\b/ },
+  { name: 'Anthropic API key', regex: /\bsk-ant-[A-Za-z0-9_-]{40,}\b/ },
+  { name: 'Google API key', regex: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+];
+
+const PII_EMAIL_REGEX = /\b[A-Za-z0-9._%+-]+@(?!example\.(?:com|org|net)\b)(?:gmail|hotmail|yahoo|outlook|live|icloud|protonmail)\.[A-Za-z]{2,}\b/i;
+
+// Validate CORE.md content. Returns { ok, errors, warnings, lineCount }.
+export function validateCore(content) {
+  const text = String(content ?? '');
+  const lines = text.split('\n');
+  const lineCount = text.endsWith('\n') ? lines.length - 1 : lines.length;
+  const errors = [];
+
+  if (lineCount > HARD_LIMIT) {
+    errors.push(`Tamanho ${lineCount} > ${HARD_LIMIT} linhas (hard limit). Curar: remover itens resolvidos (detalhe vive no vault/git).`);
+  }
+  // Pick the locale set that matches best; require it to be complete.
+  const missingBySet = Object.values(SECTION_SETS).map((set) => set.filter(({ regex }) => !regex.test(text)));
+  const best = missingBySet.reduce((a, b) => (b.length < a.length ? b : a));
+  for (const { label } of best) errors.push(`Seção obrigatória ausente: ## ${label}`);
+  for (const { name, regex } of SECRET_PATTERNS) {
+    const m = text.match(regex);
+    if (m) errors.push(`Possível ${name} detectado: "${m[0].slice(0, 30)}..." — substituir por [REDACTED_SECRET].`);
+  }
+  const em = text.match(PII_EMAIL_REGEX);
+  if (em) errors.push(`Email real detectado: "${em[0]}" — usar user@example.com.`);
+
+  const warnings = [];
+  if (lineCount >= SOFT_LIMIT && lineCount <= HARD_LIMIT) {
+    warnings.push(`Tamanho ${lineCount}/${HARD_LIMIT} linhas — perto do limite; remover itens resolvidos (≥${SOFT_LIMIT}).`);
+  }
+
+  return { ok: errors.length === 0, errors, warnings, lineCount };
+}
+
+// The seeded CORE.md (must pass validateCore). Bootstraps the 3 sections so the
+// curated hot layer exists with the right shape from day one.
+export function renderCoreSkeleton(localeId = 'pt-BR') {
+  if (localeId === 'en') {
+    return `# CORE — curated memory core (.brain)
+
+> RULE #1 — the project's canonical memory. Hand-curated, 25-line cap (validate: \`wendkeep validate-memory\`). Volatile facts live in DIGEST.md (auto). Depth: /brain-recall <topic>.
+
+## User Preferences
+- (durable preferences: language, style, conventions)
+
+## Active Patterns
+- (active patterns/architecture another agent must know)
+
+## Open Items
+- (open items/decisions — remove when resolved)
+`;
+  }
+  return `# CORE — núcleo curado da memória (.brain)
+
+> REGRA #1 — memória canônica do projeto. Curado à mão, cap 25 linhas (valide: \`wendkeep validate-memory\`). Volátil vive no DIGEST.md (auto). Profundidade: /brain-recall <tópico>.
+
+## Preferências do Usuário
+- (preferências duráveis: idioma, estilo, convenções)
+
+## Padrões Ativos
+- (padrões/arquitetura ativos que outro agente precise saber)
+
+## Pendências Abertas
+- (pendências/decisões em aberto — remova quando resolvidas)
+`;
+}
+
+// The compaction-protocol reference doc dropped into the vault.
+export function renderCompactionProtocol() {
+  return `# Protocolo de Memória — núcleo curado + digest automático (.brain)
+
+> Como cada agente recebe, consulta e persiste memória entre sessões no seu vault.
+
+## 1. Duas camadas
+
+- **QUENTE** (auto-injetada por sessão, budget ~45 linhas):
+  - \`.brain/CORE.md\` — curado à mão, **≤25 linhas** (1 item/linha): preferências, padrões, pendências.
+  - \`.brain/DIGEST.md\` — auto-gerado (0 token LLM, ≤15 linhas): decisões/sessões/bugs/aprendizados recentes.
+- **FRIA** (sob demanda):
+  - \`.brain/index.jsonl\` — índice de todas as sessões (1/linha, frontmatter).
+  - Vault: \`02-Sessões/**\`, \`04-Decisões/**\`, \`05-Bugs/**\`, \`06-Aprendizados/**\`. Desce via \`/brain-recall <tópico>\`.
+
+## 2. Compactação = regra de geração (sem trabalho manual)
+
+- **DIGEST se auto-compacta**: caps determinísticos (5 decisões, 4 sessões, 2 bugs, 2 aprendizados + \`+N mais\`). O velho cai do quente sozinho e permanece no índice/vault. **NUNCA editar** \`DIGEST.md\`/\`index.jsonl\`.
+- **CORE**: quando ≥22 linhas (soft warning), remover itens resolvidos/obsoletos — o detalhe já vive no vault e no histórico do git.
+
+## 3. O que escrever no CORE
+
+Só estado **durável** que outro agente precise saber — preferência, padrão ativo, pendência aberta. 1 linha por item. Nunca log de sessão (isso é automático no vault).
+
+3 seções fixas (obrigatórias): \`## Preferências do Usuário\`, \`## Padrões Ativos\`, \`## Pendências Abertas\`.
+
+## 4. Sem segredos / PII
+
+\`CORE.md\` nunca contém tokens (\`sk_*\`, \`whsec_*\`, JWT, Bearer), API keys, senhas ou email/telefone real. Use \`[REDACTED_SECRET]\` / \`user@example.com\`.
+
+## 5. Validação
+
+\`\`\`bash
+wendkeep validate-memory          # valida <vault>/.brain/CORE.md
+wendkeep validate-memory <path>   # valida outro arquivo
+\`\`\`
+
+Checa: cap 25 (soft 22), 3 seções, sem segredos/PII. Exit 0 = OK, 1 = falha.
+`;
+}
+
+// CLI entry for `wendkeep validate-memory [path]`. Resolves the target from an
+// explicit path, else <vault>/.brain/CORE.md (--vault or OBSIDIAN_VAULT_PATH).
+export function runValidateMemory(argv) {
+  let target;
+  let vault;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+    else if (!a.startsWith('-')) target = a;
+  }
+  if (!target) {
+    const base = vault || process.env.OBSIDIAN_VAULT_PATH;
+    if (!base) {
+      process.stderr.write('wendkeep validate-memory: no target. Pass a path, --vault <path>, or set OBSIDIAN_VAULT_PATH.\n');
+      process.exit(2);
+    }
+    target = join(base, '.brain', 'CORE.md');
+  }
+  const abs = isAbsolute(target) ? target : resolve(process.cwd(), target);
+  if (!existsSync(abs)) {
+    process.stderr.write(`wendkeep validate-memory: not found: ${abs}\n`);
+    process.exit(2);
+  }
+  const res = validateCore(readFileSync(abs, 'utf8'));
+  if (!res.ok) {
+    process.stderr.write(`❌  CORE.md viola protocolo (${res.errors.length} erro${res.errors.length > 1 ? 's' : ''}):\n`);
+    for (const e of res.errors) process.stderr.write(`   - ${e}\n`);
+    process.stderr.write('\nProtocolo: .brain/COMPACTION_PROTOCOL.md\n');
+    process.exit(1);
+  }
+  let msg = `✅  CORE.md OK (${res.lineCount} linhas, 3/3 seções, sem segredos).`;
+  for (const w of res.warnings) msg += `\n   ⚠  ${w}`;
+  process.stdout.write(`${msg}\n`);
+  process.exit(0);
+}

package/packages/vault/src/validate-memory.mjs

@@ -0,0 +1,128 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateMemoryEvent, validateSharedMemory } from './memory-schema.mjs';
+import { assertVaultPathSafe } from './vault-path-safety.mjs';
+import { validateCore } from './validate-core.mjs';
+
+function failedComponent(errors, extra = {}) {
+  return { ok: false, errors: Array.isArray(errors) ? errors : [errors], warnings: [], ...extra };
+}
+
+function readRequired(vaultBase, path, label) {
+  let checked;
+  try {
+    checked = assertVaultPathSafe(vaultBase, path, {
+      expectedType: 'file', label: `artefato ${label}`,
+    });
+  } catch (error) {
+    return { ok: false, error: `${label} inseguro: ${error?.message || error}` };
+  }
+  if (!checked.exists) return { ok: false, error: `${label} ausente: ${path}` };
+  try {
+    // Deliberately adjacent to the open performed by readFileSync.
+    checked = assertVaultPathSafe(vaultBase, checked.target, {
+      allowMissing: false, expectedType: 'file', label: `artefato ${label}`,
+    });
+    return { ok: true, content: readFileSync(checked.target, '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(vaultBase, 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(vaultBase, 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(vaultBase, 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(vaultBase, 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 });
+}