neurain 0.1.0-alpha.0

package/src/core/compile_desk.mjs

@@ -0,0 +1,324 @@
+// `compile` command (W-B, read-only desk). The interactive !compile picker: it
+// reads the pending writeback queue + the source-digest manifest and returns a
+// priority-ranked candidate desk (safe queue items first, then high-value
+// uncompiled raw by score), with private / needs-decision / official-memory items
+// surfaced separately and NEVER silently mixed in. It reads no raw bodies and
+// writes nothing. Faithful port of the vault neurain-compile tool (nondeterministic
+// elapsed timing dropped; parity normalizes).
+import path from 'node:path';
+import { absPath, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { readJsonSafe, readJsonl } from './vault_state.mjs';
+
+function manifestEntries(value) {
+  return Object.values((value && value.files) || {});
+}
+
+function isCompiled(entry) {
+  return ['compiled', 'flushed', 'archived', 'superseded'].includes(entry.status) || (entry.compiled_to || []).length > 0;
+}
+
+function compiledEntries(value) {
+  return manifestEntries(value).filter((entry) => isCompiled(entry));
+}
+
+function uncompiledEntries(value) {
+  return manifestEntries(value).filter((entry) => !isCompiled(entry));
+}
+
+function inferTargetLayer(item) {
+  if (item.write_intent === 'update_current') return 'current';
+  if (item.write_intent === 'create_task') return 'task_memory';
+  if (item.write_intent === 'output_request') return 'output';
+  if (item.write_intent === 'evidence_only') return 'raw';
+  return 'wiki';
+}
+
+function inferFlushLevel(item) {
+  if (item.requires_user_decision || item.sensitivity === 'private') return 'full';
+  if (['update_current', 'create_task'].includes(item.write_intent)) return 'full';
+  if (item.write_intent === 'evidence_only') return 'light';
+  return 'standard';
+}
+
+function reviewReasons(item) {
+  const reasons = [];
+  const targetLayer = item.target_layer || inferTargetLayer(item);
+  if (item.requires_user_decision) reasons.push('requires user decision');
+  if (item.sensitivity === 'private') reasons.push('private source');
+  if (['current', 'fact_ledger', 'task_memory'].includes(targetLayer)) reasons.push('official memory layer');
+  if (String(item.flush_level || inferFlushLevel(item)).toLowerCase() === 'full') reasons.push('permanent save (needs confirmation)');
+  return [...new Set(reasons)];
+}
+
+function summarizeQueueItem(item, reasons = []) {
+  return {
+    source_id: item.source_id || '',
+    title: item.title || '',
+    raw_path: item.raw_path || '',
+    target_layer: item.target_layer || inferTargetLayer(item),
+    target_path: item.target_path || '',
+    sensitivity: item.sensitivity || 'internal',
+    flush_level: item.flush_level || inferFlushLevel(item),
+    reasons,
+  };
+}
+
+function deepCompileCandidates(value) {
+  return uncompiledEntries(value)
+    .filter((entry) => Number(entry.high_value_score || 0) >= 2)
+    .sort((a, b) => Number(b.high_value_score || 0) - Number(a.high_value_score || 0) || Number(b.size_bytes || 0) - Number(a.size_bytes || 0))
+    .map((entry) => ({
+      path: entry.path,
+      source_id: entry.source_id || '',
+      source_type: entry.source_type || '',
+      sensitivity: entry.sensitivity || 'internal',
+      high_value_score: entry.high_value_score || 0,
+      reasons: entry.high_value_reasons || [],
+    }));
+}
+
+function priorityLabel(score) {
+  const s = Number(score || 0);
+  if (s >= 4) return 'high';
+  if (s >= 2) return 'medium';
+  return 'low';
+}
+
+function rankedCandidates({ safe: safeItems, deep }) {
+  const out = [];
+  for (const item of safeItems) {
+    out.push({
+      kind: 'queue_item',
+      source_id: item.source_id || '',
+      title: item.title || '',
+      sensitivity: item.sensitivity || 'internal',
+      priority: 'queue-ready',
+      score: 1000,
+      target_layer: item.target_layer || inferTargetLayer(item),
+    });
+  }
+  for (const c of deep) {
+    out.push({
+      kind: 'raw_source',
+      source_id: c.source_id || '',
+      title: c.path || '',
+      sensitivity: c.sensitivity || 'internal',
+      priority: priorityLabel(c.high_value_score),
+      score: Number(c.high_value_score || 0),
+      reasons: c.reasons || [],
+    });
+  }
+  return out.sort((a, b) => b.score - a.score).map((c, i) => ({ rank: i + 1, ...c }));
+}
+
+function summarizeManifestTarget(entry, selectedBy) {
+  return {
+    kind: 'raw_source',
+    selected_by: selectedBy,
+    source_id: entry.source_id || '',
+    path: entry.path,
+    source_type: entry.source_type || '',
+    sensitivity: entry.sensitivity || 'internal',
+    status: entry.status || 'discovered',
+    high_value_score: entry.high_value_score || 0,
+    reasons: entry.high_value_reasons || [],
+    compiled_to: entry.compiled_to || [],
+  };
+}
+
+function selectTarget(query, value, queueItems, rawDir) {
+  const lower = String(query || '').toLowerCase();
+  const sourceIdMatch = String(query || '').match(/\b(?:raw-\d{8}-\d{3}|clipper-\d{8}-\d{6})\b/);
+  if (sourceIdMatch) {
+    const sourceId = sourceIdMatch[0];
+    const queueMatch = queueItems.find((item) => item.source_id === sourceId);
+    if (queueMatch) return { kind: 'queue_item', ...summarizeQueueItem(queueMatch, reviewReasons(queueMatch)) };
+    const manifestMatch = manifestEntries(value).find((entry) => entry.source_id === sourceId);
+    if (manifestMatch) return summarizeManifestTarget(manifestMatch, 'source_id');
+  }
+
+  const rawPathMatch = String(query || '').match(new RegExp(`\\b${rawDir}\\/[^\\n\\r]+`));
+  if (rawPathMatch) {
+    const rawPath = rawPathMatch[0].trim();
+    const manifestMatch = manifestEntries(value).find((entry) => entry.path === rawPath || entry.path.includes(rawPath));
+    if (manifestMatch) return summarizeManifestTarget(manifestMatch, 'raw_path');
+  }
+
+  if (/latest|recent|최근|방금|clip/.test(lower)) {
+    const entries = uncompiledEntries(value).filter((entry) => {
+      if (/clip|web|영상|youtube|유튜브/.test(lower)) return String(entry.path || '').startsWith(`${rawDir}/web/`);
+      return true;
+    });
+    const latest = entries.sort((a, b) => Number(b.mtime_ms || 0) - Number(a.mtime_ms || 0))[0];
+    if (latest) return summarizeManifestTarget(latest, 'latest');
+  }
+  return null;
+}
+
+function selectAutoTarget({ safe: safeItems, needsConfirmation: confirmationItems, manifest: value, sessionId: targetSessionId }) {
+  if (safeItems.length > 0) {
+    const item = safeItems[0];
+    return { auto_selected: true, selected_by: 'safe_queue', kind: 'queue_item', ...summarizeQueueItem(item, []) };
+  }
+  if (confirmationItems.length > 0) return null;
+
+  const latestSmallSource = uncompiledEntries(value)
+    .filter((entry) => ['public', 'internal'].includes(entry.sensitivity || 'internal'))
+    .filter((entry) => Number(entry.size_bytes || 0) <= 250000)
+    .filter((entry) => {
+      if (!targetSessionId) return true;
+      const pathText = String(entry.path || '').toLowerCase();
+      return !pathText.includes('/parents/') || targetSessionId.startsWith('parents-');
+    })
+    .sort((a, b) => Number(b.mtime_ms || 0) - Number(a.mtime_ms || 0))[0];
+  if (latestSmallSource) return { auto_selected: true, ...summarizeManifestTarget(latestSmallSource, 'latest_safe_raw') };
+
+  const topDigestCandidate = deepCompileCandidates(value)
+    .map((entry) => manifestEntries(value).find((candidate) => candidate.path === entry.path))
+    .filter(Boolean)
+    .filter((entry) => ['public', 'internal'].includes(entry.sensitivity || 'internal'))
+    .filter((entry) => Number(entry.size_bytes || 0) <= 500000)
+    .find(Boolean);
+  if (topDigestCandidate) return { auto_selected: true, ...summarizeManifestTarget(topDigestCandidate, 'high_value_safe_raw') };
+
+  return null;
+}
+
+function nextAction({ selected, safe: safeItems, needsConfirmation: confirmationItems, deepCandidates: candidates }) {
+  if (selected && selected.sensitivity === 'private') return 'Ask before compiling this private source into official memory.';
+  if (selected) return 'Compile this selected source only. Do not scan or read unrelated raw files.';
+  if (safeItems.length === 1) return 'One safe queue item is ready. Compile only that item if the user wants automatic progress.';
+  if (safeItems.length > 1) return 'Multiple safe queue items exist. Show the shortlist and process one at a time.';
+  if (confirmationItems.length > 0) return 'Only confirmation-needed items are pending. Ask before official memory changes.';
+  if (candidates.length > 0) return 'Show deep compile candidates. Do not deep read any candidate until one is selected.';
+  return 'Nothing useful is waiting for compile.';
+}
+
+export async function compileCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const rawDir = vaultCfg.raw_dir;
+  const positional = args._.slice(1).join(' ').trim();
+  const detail = String(args.target || args.text || positional || '').trim();
+  const sessionId = String(args['session-id'] || '');
+  const top = Number(args.top || 5);
+  const manifestRel = String(args.manifest || vaultCfg.source_digest_manifest);
+  const queueRel = String(args.queue || vaultCfg.writeback_queue);
+
+  const manifest = readJsonSafe(path.join(root, manifestRel), null);
+  const pending = readJsonl(path.join(root, queueRel)).filter((row) => {
+    if (row.status !== 'pending') return false;
+    if (!sessionId) return true;
+    return row.session_id === sessionId;
+  });
+
+  const safe = pending.filter((item) => reviewReasons(item).length === 0);
+  const needsConfirmation = pending
+    .filter((item) => reviewReasons(item).length > 0)
+    .map((item) => {
+      const s = summarizeQueueItem(item, reviewReasons(item));
+      // Never expose a private item's file paths in output (R3-#1).
+      if (s.sensitivity === 'private') { s.raw_path = '[redacted:private]'; s.target_path = ''; }
+      return s;
+    });
+
+  const allDeep = deepCompileCandidates(manifest);
+  const safeDeep = allDeep.filter((e) => ['public', 'internal'].includes(e.sensitivity || 'internal'));
+  const excludedDeep = allDeep
+    .filter((e) => !['public', 'internal'].includes(e.sensitivity || 'internal'))
+    .map((e) => ({ source_id: e.source_id || '', title: '[private/sensitive raw source]', sensitivity: e.sensitivity || 'private', reasons: ['private/sensitive raw source'] }));
+  const deepCandidates = safeDeep.slice(0, top);
+  const candidates = rankedCandidates({ safe, deep: safeDeep }).slice(0, 20);
+  const excludedAll = [...needsConfirmation, ...excludedDeep];
+
+  const wantList = Boolean(args.list || args.pick);
+  const wantAuto = Boolean(args.auto);
+  const deskOnly = Boolean(args.desk || args['no-auto-select']) || wantList || (!detail && !wantAuto);
+  const selected = detail
+    ? selectTarget(detail, manifest, pending, rawDir)
+    : deskOnly
+      ? null
+      : selectAutoTarget({ safe, needsConfirmation, manifest, sessionId });
+  const mode = selected
+    ? (selected.auto_selected ? 'auto_selected_compile_plan' : 'selected_compile_plan')
+    : deskOnly
+      ? 'compile_desk_fast'
+      : needsConfirmation.length > 0
+        ? 'compile_confirmation_required'
+        : 'compile_desk_fast';
+  const noTarget = !selected;
+
+  const payload = {
+    ok: true,
+    generated_at: timestamp(),
+    command: 'compile',
+    durable_write: false,
+    mode,
+    session_id: sessionId || null,
+    target_query: detail || null,
+    performance_policy: {
+      default_target_seconds: noTarget ? 5 : 60,
+      raw_full_reads_allowed: noTarget ? 0 : 1,
+      broad_raw_scan_allowed: false,
+      deep_compile_requires_selected_target: true,
+    },
+    queue: {
+      pending_count: pending.length,
+      safe_count: safe.length,
+      needs_confirmation_count: needsConfirmation.length,
+      safe: safe.slice(0, top).map((item) => summarizeQueueItem(item, [])),
+      needs_confirmation: needsConfirmation.slice(0, top),
+    },
+    source_digest: {
+      manifest: manifestRel,
+      available: Boolean(manifest),
+      compiled_count: compiledEntries(manifest).length,
+      uncompiled_count: uncompiledEntries(manifest).length,
+      deep_compile_candidate_count: safeDeep.length,
+      deep_compile_candidates: deepCandidates,
+    },
+    selected_target: selected,
+    candidate_count: candidates.length,
+    candidates,
+    excluded: excludedAll,
+    next_action: nextAction({ selected, safe, needsConfirmation, deepCandidates }),
+    mutates_canonical: false,
+    user_explanation: selected
+      ? (selected.auto_selected
+        ? 'No target was specified. One safe compile target was selected automatically. Read only this source, then update the minimal wiki or area target and sync the area brief.'
+        : 'Selected compile target found. Read only this source, then update the minimal wiki or area target and sync the area brief.')
+      : deskOnly
+        ? 'Desk mode selected. This fast desk only shows what can be compiled and does not read raw bodies.'
+        : 'No safe compile target was selected. This desk shows candidates and does not read raw bodies.',
+  };
+
+  if (args.json) return { json: true, payload };
+  return { text: render(payload) };
+}
+
+function render(value) {
+  const lines = ['# Neurain Compile Desk', ''];
+  lines.push(`- Mode: ${value.mode}`);
+  lines.push(`- Pending queue: ${value.queue.pending_count}`);
+  lines.push(`- Safe queue: ${value.queue.safe_count}`);
+  lines.push(`- Needs confirmation: ${value.queue.needs_confirmation_count}`);
+  lines.push(`- Deep compile candidates: ${value.source_digest.deep_compile_candidate_count}`);
+  lines.push(`- Raw full reads allowed: ${value.performance_policy.raw_full_reads_allowed}`);
+  if (value.candidates && value.candidates.length) {
+    lines.push('', `## Candidates (priority order): ${value.candidates.length}`);
+    for (const c of value.candidates) {
+      lines.push(`  ${c.rank}. [${c.priority}] ${c.title || c.source_id || c.kind}${c.source_id ? `  (${c.source_id})` : ''}`);
+    }
+  }
+  if (value.excluded && value.excluded.length) {
+    lines.push('', `제외(확인필요/비공개) ${value.excluded.length}건: ${value.excluded.map((e) => e.title || e.source_id).join(', ')}`);
+  }
+  if (value.candidates && value.candidates.length) {
+    lines.push('', '몇 건 정리할까요? (숫자 1–10; "전부"는 안전한 것 최대 10건 + 나머지 개수 공시)');
+  } else if (!value.selected_target && value.excluded && value.excluded.length) {
+    lines.push('', '정리 가능한 안전 후보가 없습니다. 위 제외 항목은 확인/승인 후에만 처리됩니다.');
+  }
+  lines.push(`- Next action: ${value.next_action}`);
+  return lines.join('\n');
+}

package/src/core/complete.mjs

@@ -0,0 +1,108 @@
+// `complete` command (W-B, B4, durable). Marks a captured source compiled: it
+// updates the _inbox envelope, rewrites the matching writeback-queue row UNDER A
+// LOCK (re-reading inside the lock so a concurrent append is never lost), and
+// appends one wiki/log line. Faithful port of the vault neurain-complete.
+//
+// W-D BOUNDARY: the engine NEVER writes session-state.json, the handoff .md, or
+// the area brief .md. It returns a session_state_delta carrying the patch +
+// handoff_note + area_brief_note the future vault shuttle applies; pending_count
+// is ADVISORY (the shuttle recomputes at apply time). See the B4 cross-review.
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { loadSessionState, pendingCountForSession, readJsonl, readJsonSafe } from './vault_state.mjs';
+import { atomicWriteJson } from './durable.mjs';
+import { rewriteQueueLocked } from './queue_write.mjs';
+import { normalizeList } from './envelope.mjs';
+import { appendWikiLog } from './wiki_log.mjs';
+
+export async function completeCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const sourceId = String(args['source-id'] || '');
+  if (!sourceId) return done(args, { ok: false, command: 'complete', durable_write: false, error: 'Missing --source-id.' }, 1);
+
+  const compiledTo = normalizeList(args['compiled-to']);
+  if (compiledTo.length === 0) return done(args, { ok: false, command: 'complete', durable_write: false, error: 'Missing --compiled-to path list.' }, 1);
+
+  const envelopeRel = `${vaultCfg.raw_inbox_dir}/${sourceId}.json`;
+  const envelopeAbs = path.join(root, envelopeRel);
+  const envelope = readJsonSafe(envelopeAbs, null);
+  if (!envelope) return done(args, { ok: false, command: 'complete', durable_write: false, error: `Envelope not found: ${envelopeRel}` }, 1);
+
+  const missingTargets = compiledTo.filter((target) => !fs.existsSync(path.join(root, target)));
+  if (missingTargets.length > 0) return done(args, { ok: false, command: 'complete', durable_write: false, error: `Compiled target missing: ${missingTargets.join(', ')}` }, 1);
+
+  const completedAt = args['completed-at'] || timestamp();
+  const status = args.status || 'compiled';
+  let sessionId = envelope.session_id || '';
+  // if the envelope has no session, recover it from the matching queue row
+  if (!sessionId) {
+    const row = readJsonl(path.join(root, vaultCfg.writeback_queue)).find((r) => r && r.source_id === sourceId && r.session_id);
+    if (row) sessionId = row.session_id;
+  }
+
+  const updatedEnvelope = {
+    ...envelope,
+    status,
+    compiled_to: [...new Set([...(envelope.compiled_to || []), ...compiledTo])],
+    completed_at: completedAt,
+  };
+
+  if (args['dry-run']) {
+    return done(args, { ok: true, command: 'complete', durable_write: false, dry_run: true, source_id: sourceId, status, compiled_to: updatedEnvelope.compiled_to, session_id: sessionId });
+  }
+
+  atomicWriteJson(envelopeAbs, updatedEnvelope);
+
+  let queueUpdated = false;
+  if (fs.existsSync(path.join(root, vaultCfg.writeback_queue))) {
+    rewriteQueueLocked(root, vaultCfg, (rows) => rows.map((row) => {
+      if (row.source_id !== sourceId) return row;
+      queueUpdated = true;
+      return { ...row, status, compiled_at: completedAt, compiled_to: [...new Set([...(row.compiled_to || []), ...compiledTo])] };
+    }));
+  }
+
+  appendWikiLog(root, vaultCfg, 'compile', envelope.title || sourceId, [
+    `Source: ${sourceId}`, `Compiled to: ${compiledTo.join(', ')}`, `Status: ${status}`,
+  ]);
+
+  let sessionStateDelta = null;
+  if (sessionId) {
+    let session = null;
+    try { session = (loadSessionState(root, vaultCfg).sessions || {})[sessionId] || null; } catch { session = null; }
+    const pendingCount = pendingCountForSession(root, vaultCfg, sessionId); // after rewrite
+    const patch = { last_pulse: completedAt, last_flush: completedAt, pending_count: pendingCount };
+    const summary = `Compiled ${envelope.title || sourceId} to ${compiledTo.join(', ')}.`;
+    sessionStateDelta = {
+      applied: false,
+      reason: 'reserved-for-W-D: engine never writes session-state / handoff / area brief; the vault shuttle applies these.',
+      recompute_pending_at_apply: true,
+      session_id: sessionId,
+      patch,
+      handoff_note: { session_id: sessionId, summary, now: completedAt, state_patch: patch },
+      area_brief_note: session && session.area ? { area: session.area, session_id: sessionId, summary, now: completedAt, sensitivity: session.sensitivity } : null,
+    };
+  }
+
+  return done(args, {
+    ok: true, command: 'complete', durable_write: true,
+    source_id: sourceId, status, compiled_to: updatedEnvelope.compiled_to,
+    queue_updated: queueUpdated, session_id: sessionId,
+    session_state_delta: sessionStateDelta,
+  });
+}
+
+function done(args, payload, exitCode) {
+  if (exitCode !== undefined) process.exitCode = exitCode;
+  if (args.json) return { json: true, payload };
+  if (!payload.ok) return { text: `# Complete Writeback\n\n- ${payload.error}` };
+  const lines = ['# Complete Writeback', '', `- Source ID: ${payload.source_id}`, `- Status: ${payload.status}`];
+  if (payload.session_id) lines.push(`- Session: ${payload.session_id}`);
+  lines.push(`- Queue updated: ${payload.queue_updated ? 'yes' : 'no'}`);
+  lines.push(`- Compiled to: ${(payload.compiled_to || []).join(', ')}`);
+  if (payload.session_state_delta) lines.push('- Session-state delta (unapplied) returned for the vault shuttle.');
+  return { text: lines.join('\n') };
+}

package/src/core/config.mjs

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Read neurain.config.json from a target root. Mirrors doctor.readConfig: a
+// missing or unreadable config is never fatal (recall must keep working against
+// an un-initialized folder), so callers get an empty object and fall back to the
+// engine defaults below. The structural defaults match `neurain init` and the
+// reference vault layout, so the engine works against either with no config.
+export function readConfig(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, 'neurain.config.json'), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+const STRUCTURAL_DEFAULTS = {
+  areas_dir: '10_areas',
+  wiki_dir: 'wiki',
+  system_dir: '00_system',
+  hubs_dir: '20_hubs',
+  archive_dir: '90_archive',
+  output_dir: 'output',
+  raw_dir: 'raw',
+};
+
+const RECALL_DEFAULTS = {
+  include: [],
+  exclude: [],
+  labels: {
+    default_sensitivity: 'internal',
+    // null => labels.DEFAULT_PATH_MARKERS (kept there so the marker vocabulary
+    // and its boundary semantics live in one module).
+    path_markers: null,
+    areas: {},
+  },
+  intel: {
+    registry: '00_system/neurain/search-index-registry.json',
+    aliases: '00_system/neurain/search-aliases.json',
+    queue: '00_system/neurain/writeback-queue.jsonl',
+    memory_write_registry: '00_system/neurain/memory-write-registry.json',
+  },
+  routing: { enabled: null, max_per_layer: 3 },
+  bench: { baseline_source_recall: null },
+};
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+// Structural file/dir paths used by the read-only view tools (status, digest,
+// queue, review-queue). Defaults match the reference vault layout and the keys
+// the vault's own config exposes; any can be overridden at the top level of
+// neurain.config.json so a different layout works identically.
+const VAULT_PATH_DEFAULTS = {
+  session_state: '00_system/sessions/session-state.json',
+  wrap_journal: '00_system/sessions/wrap-journal.jsonl',
+  session_handoff_dir: '00_system/sessions/handoffs',
+  writeback_queue: '00_system/neurain/writeback-queue.jsonl',
+  writeback_queue_archive: '00_system/neurain/writeback-queue.archive.jsonl',
+  source_digest_manifest: '00_system/neurain/source-digest-manifest.json',
+  search_index_registry: '00_system/neurain/search-index-registry.json',
+};
+
+// Structural directory keys the W-B capture/queue/compile pipeline needs (raw
+// capture roots, output drafts). Match the vault's neurain-config defaults and
+// the recall STRUCTURAL_DEFAULTS so route/plan-writeback/compile resolve the same
+// paths the legacy tools do. Overridable at the top level of neurain.config.json.
+const VAULT_DIR_DEFAULTS = {
+  areas_dir: '10_areas',
+  wiki_dir: 'wiki',
+  system_dir: '00_system',
+  hubs_dir: '20_hubs',
+  archive_dir: '90_archive',
+  output_dir: 'output',
+  raw_dir: 'raw',
+  raw_inbox_dir: 'raw/_inbox',
+};
+
+const STATUS_REQUIRED_FILES_DEFAULT = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  '00_system/neurain-startup.md',
+  'index.md',
+  'wiki/index.md',
+  '00_system/area-registry.md',
+  '00_system/sessions/session-registry.md',
+];
+
+export function vaultConfig(root, config = readConfig(root)) {
+  const out = {};
+  for (const [key, fallback] of Object.entries(VAULT_DIR_DEFAULTS)) {
+    out[key] = typeof config[key] === 'string' && config[key] ? config[key] : fallback;
+  }
+  for (const [key, fallback] of Object.entries(VAULT_PATH_DEFAULTS)) {
+    out[key] = typeof config[key] === 'string' && config[key] ? config[key] : fallback;
+  }
+  const r = asObject(config.recall);
+  out.status_required_files = Array.isArray(r.status_required_files) ? r.status_required_files : STATUS_REQUIRED_FILES_DEFAULT;
+  return out;
+}
+
+// Merge the recall block over engine defaults. Structural dir keys are read from
+// the top-level config (matching neurain.config.json's existing shape); the
+// recall-specific knobs live under `config.recall`. Every field is optional and
+// defaulted, so the reference vault (which has no config file yet) hits the same
+// behavior as an explicitly configured adopter.
+export function recallConfig(root, config = readConfig(root)) {
+  const structural = {};
+  for (const [key, fallback] of Object.entries(STRUCTURAL_DEFAULTS)) {
+    structural[key] = typeof config[key] === 'string' && config[key] ? config[key] : fallback;
+  }
+  const r = asObject(config.recall);
+  const labels = asObject(r.labels);
+  const intel = asObject(r.intel);
+  const routing = asObject(r.routing);
+  const bench = asObject(r.bench);
+  return {
+    ...structural,
+    include: Array.isArray(r.include) ? r.include : RECALL_DEFAULTS.include,
+    exclude: Array.isArray(r.exclude) ? r.exclude : RECALL_DEFAULTS.exclude,
+    labels: {
+      default_sensitivity: labels.default_sensitivity || RECALL_DEFAULTS.labels.default_sensitivity,
+      path_markers: Array.isArray(labels.path_markers) ? labels.path_markers : RECALL_DEFAULTS.labels.path_markers,
+      areas: asObject(labels.areas),
+    },
+    intel: {
+      registry: intel.registry || RECALL_DEFAULTS.intel.registry,
+      aliases: intel.aliases || RECALL_DEFAULTS.intel.aliases,
+      queue: intel.queue || RECALL_DEFAULTS.intel.queue,
+      memory_write_registry: intel.memory_write_registry || RECALL_DEFAULTS.intel.memory_write_registry,
+    },
+    routing: {
+      enabled: 'enabled' in routing ? routing.enabled : RECALL_DEFAULTS.routing.enabled,
+      max_per_layer: Number.isFinite(Number(routing.max_per_layer)) ? Number(routing.max_per_layer) : RECALL_DEFAULTS.routing.max_per_layer,
+    },
+    bench: {
+      baseline_source_recall: Number.isFinite(Number(bench.baseline_source_recall)) ? Number(bench.baseline_source_recall) : RECALL_DEFAULTS.bench.baseline_source_recall,
+    },
+  };
+}