neurain 0.1.0-alpha.0

package/src/core/plan_receipt.mjs

@@ -0,0 +1,177 @@
+// `plan-receipt` command (W-B). Validates an agent's declared write PLAN against
+// the ACTUAL write set: required planned writes must be present, unplanned durable
+// writes fail unless explicitly allowed. Its only write is an optional receipt
+// under output/receipts/plan-receipts/ (never canonical knowledge). Faithful port
+// of the vault neurain-plan-receipt tool. CLI-only in W-B.
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { absPath, readText, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { atomicWriteJson } from './durable.mjs';
+
+function readJsonAt(root, rel) {
+  const abs = path.join(root, String(rel));
+  return JSON.parse(readText(abs, '')); // throws on missing/empty -> caught by command
+}
+
+function normalizePathList(values) {
+  const out = [];
+  for (const value of Array.isArray(values) ? values : [values]) {
+    const rel = String(value || '').trim().replace(/\\/g, '/');
+    if (!rel) continue;
+    if (path.isAbsolute(rel) || rel === '..' || rel.startsWith('../') || rel.includes('/../')) {
+      throw new Error(`Unsafe path in plan/actual: ${rel}`);
+    }
+    out.push(rel);
+  }
+  return [...new Set(out)].sort();
+}
+
+function normalizePlan(value) {
+  return {
+    label: String(value.label || value.plan_id || 'write-plan'),
+    required_writes: normalizePathList(value.required_writes || value.required || []),
+    optional_writes: normalizePathList(value.optional_writes || value.optional || []),
+    storage_only: normalizePathList(value.storage_only || []),
+  };
+}
+
+function normalizeActual(value) {
+  return {
+    durable_writes: normalizePathList(value.durable_writes || value.writes || value.actual_writes || []),
+    storage_only: normalizePathList(value.storage_only || []),
+  };
+}
+
+function hash(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function slug(value) {
+  return String(value || 'write-plan')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'write-plan';
+}
+
+export function validatePlan(plan, actual, options = {}) {
+  const required = new Set(plan.required_writes);
+  const optional = new Set(plan.optional_writes);
+  const allowedStorage = new Set(plan.storage_only);
+  const durable = new Set(actual.durable_writes);
+  const actualStorage = new Set(actual.storage_only);
+  const missingRequired = [...required].filter((rel) => !durable.has(rel));
+  const missingOptional = [...optional].filter((rel) => !durable.has(rel));
+  const plannedDurable = new Set([...required, ...optional]);
+  const unplannedDurable = [...durable].filter((rel) => !plannedDurable.has(rel));
+  const unplannedStorage = [...actualStorage].filter((rel) => !allowedStorage.has(rel));
+  const ok = missingRequired.length === 0 && (options.allowUnplanned || unplannedDurable.length === 0);
+  return {
+    ok,
+    command: 'plan-receipt',
+    durable_write: false,
+    tool: 'neurain-plan-receipt',
+    generated_at: timestamp(),
+    label: String(options.label || plan.label || 'write-plan'),
+    plan_hash: hash(JSON.stringify(plan)),
+    actual_hash: hash(JSON.stringify(actual)),
+    validation: {
+      required_writes: plan.required_writes,
+      optional_writes: plan.optional_writes,
+      actual_durable_writes: actual.durable_writes,
+      storage_only_allowed: plan.storage_only,
+      actual_storage_only: actual.storage_only,
+      missing_required: missingRequired,
+      missing_optional: missingOptional,
+      unplanned_durable: unplannedDurable,
+      unplanned_storage: unplannedStorage,
+      allow_unplanned: Boolean(options.allowUnplanned),
+    },
+    failures: [
+      ...missingRequired.map((rel) => `missing required write: ${rel}`),
+      ...(options.allowUnplanned ? [] : unplannedDurable.map((rel) => `unplanned durable write: ${rel}`)),
+    ],
+    notes: [
+      'Required planned writes must be present in actual durable writes.',
+      'Optional or idempotent planned writes can be absent but are surfaced in missing_optional.',
+      'Unplanned durable writes fail unless --allow-unplanned is explicitly passed.',
+    ],
+  };
+}
+
+function runSelftest() {
+  const passing = validatePlan(
+    { label: 'selftest-pass', required_writes: ['wiki/source-summaries/example.md'], optional_writes: ['wiki/index.md'], storage_only: ['output/receipts/example.json'] },
+    { durable_writes: ['wiki/source-summaries/example.md'], storage_only: ['output/receipts/example.json'] },
+  );
+  const missingRequired = validatePlan(
+    { label: 'selftest-missing', required_writes: ['wiki/a.md'], optional_writes: [], storage_only: [] },
+    { durable_writes: [], storage_only: [] },
+  );
+  const unplanned = validatePlan(
+    { label: 'selftest-unplanned', required_writes: ['wiki/a.md'], optional_writes: [], storage_only: [] },
+    { durable_writes: ['wiki/a.md', 'wiki/b.md'], storage_only: [] },
+  );
+  return {
+    ok: passing.ok && !missingRequired.ok && !unplanned.ok,
+    command: 'plan-receipt',
+    durable_write: false,
+    tool: 'neurain-plan-receipt',
+    selftest: {
+      passing_ok: passing.ok,
+      missing_required_rejected: !missingRequired.ok,
+      unplanned_rejected: !unplanned.ok,
+      optional_missing_surfaced: passing.validation.missing_optional.includes('wiki/index.md'),
+    },
+  };
+}
+
+export async function planReceiptCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+
+  if (args.selftest) {
+    const result = runSelftest();
+    process.exitCode = result.ok ? 0 : 1;
+    return done(args, result);
+  }
+
+  let receipt;
+  try {
+    if (!args.plan) throw new Error('Missing --plan.');
+    if (!args.actual) throw new Error('Missing --actual.');
+    const plan = normalizePlan(readJsonAt(root, args.plan));
+    const actual = normalizeActual(readJsonAt(root, args.actual));
+    receipt = validatePlan(plan, actual, {
+      allowUnplanned: Boolean(args['allow-unplanned']),
+      label: String(args.label || plan.label || 'write-plan'),
+    });
+  } catch (error) {
+    process.exitCode = 1;
+    return done(args, { ok: false, command: 'plan-receipt', durable_write: false, error: error.message });
+  }
+
+  if (args.write) {
+    const stamp = timestamp().replace(/[:+]/g, '').replace('T', '-');
+    const rel = `${vaultCfg.output_dir}/receipts/plan-receipts/${stamp}-${slug(receipt.label)}.json`;
+    atomicWriteJson(path.join(root, rel), receipt);
+    receipt.receipt_path = rel;
+    receipt.durable_write = true; // a receipt file was written under output/receipts
+  }
+  process.exitCode = receipt.ok ? 0 : 1;
+  return done(args, receipt);
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  const lines = ['# Neurain Plan Receipt', '', `- OK: ${payload.ok ? 'yes' : 'no'}`];
+  if (payload.error) lines.push(`- Error: ${payload.error}`);
+  if (payload.label) lines.push(`- Label: ${payload.label}`);
+  if (payload.receipt_path) lines.push(`- Receipt: ${payload.receipt_path}`);
+  if (payload.failures && payload.failures.length) {
+    lines.push('', '## Failures', '');
+    for (const failure of payload.failures) lines.push(`- ${failure}`);
+  }
+  return { text: lines.join('\n') };
+}

package/src/core/plan_writeback.mjs

@@ -0,0 +1,176 @@
+// `plan-writeback` command (W-B, read-only). Builds the deterministic writeback
+// plan for a source: target layers (raw / wiki / area / output), confirmation
+// gates (private, cross-area, current/task memory), a Light/Standard/Full scope,
+// and the queue metadata a later capture would attach. Writes nothing. Faithful
+// port of the vault neurain-plan-writeback tool.
+import path from 'node:path';
+import { absPath, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { loadSessionState, readJsonSafe } from './vault_state.mjs';
+import { firstLineTitle, inferFlushLevelFromEnvelope, inferTargetLayerFromIntent } from './classify.mjs';
+import { makeEnvelope, readArgInput } from './envelope.mjs';
+
+function handoffPathFor(vaultCfg, sessionId, session) {
+  return (session && session.handoff_path) || `${vaultCfg.session_handoff_dir}/${sessionId}.md`;
+}
+
+function slugFromTitle(title) {
+  return String(title || 'untitled')
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9가-힣]+/gi, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'untitled';
+}
+
+function candidateSourceSummaryPath(vaultCfg, source) {
+  const area = (source.area_candidates || [])[0] || 'general';
+  return `${vaultCfg.wiki_dir}/source-summaries/${area}_${slugFromTitle(source.title)}.md`;
+}
+
+export function buildWritebackPlan(source, vaultCfg, dayStamp) {
+  const targets = [];
+  const gates = [];
+  const areas = source.area_candidates || [];
+  const domains = source.domain_candidates || [];
+  const sensitivity = source.sensitivity || 'internal';
+  const intent = source.write_intent || 'evidence_only';
+
+  targets.push({
+    layer: 'raw',
+    path: source.raw_path || '(capture first)',
+    action: ['captured', 'planned', 'compiled', 'flushed'].includes(source.status) && source.raw_path ? 'preserve' : 'capture',
+    required: true,
+  });
+
+  if (intent !== 'evidence_only') {
+    targets.push({
+      layer: 'wiki',
+      path: candidateSourceSummaryPath(vaultCfg, source),
+      action: 'create_or_update_source_summary',
+      required: sensitivity !== 'private',
+    });
+  }
+
+  if (areas.length === 1 && ['remember', 'update_current', 'create_task'].includes(intent)) {
+    targets.push({
+      layer: 'area',
+      path: `${vaultCfg.areas_dir}/${areas[0]}/memory_layer/`,
+      action: intent === 'update_current' ? 'update_current_or_memory' : 'append_memory_candidate',
+      required: false,
+    });
+  }
+
+  if (intent === 'output_request') {
+    targets.push({
+      layer: 'output',
+      path: `${vaultCfg.output_dir}/drafts/${dayStamp}_${slugFromTitle(source.title)}.md`,
+      action: 'draft_output_candidate',
+      required: false,
+    });
+  }
+
+  targets.push({ layer: 'wiki', path: `${vaultCfg.wiki_dir}/index.md`, action: 'update_if_page_changes', required: true });
+  targets.push({ layer: 'wiki', path: `${vaultCfg.wiki_dir}/log.md`, action: 'append_operation', required: true });
+
+  if (sensitivity === 'private') gates.push('private source: user must choose raw-only or redacted wiki summary');
+  if (source.requires_user_decision) gates.push('route requires user decision');
+  if (areas.length > 1) gates.push('cross-area update or hub creation needs confirmation');
+  if (domains.includes('personal-records') && intent === 'output_request') gates.push('private material cannot enter output without explicit approval');
+  if (intent === 'update_current') gates.push('current cache update requires Full Flush');
+  if (intent === 'create_task') gates.push('task memory update requires Full Flush');
+
+  const scope = gates.length > 0 ? 'Full' : targets.length > 3 ? 'Standard' : 'Light';
+
+  return {
+    source_id: source.source_id,
+    title: source.title,
+    session_id: source.session_id || '',
+    session_scope: source.session_scope || '',
+    scope,
+    status: gates.length > 0 ? 'blocked_for_confirmation' : 'ready',
+    gates,
+    targets,
+    queue_metadata: {
+      session_id: source.session_id || '',
+      scope: source.session_scope || '',
+      flush_level: scope === 'Full' ? 'full' : inferFlushLevelFromEnvelope(source),
+      target_layer: inferTargetLayerFromIntent(source.write_intent),
+      target_path: '',
+      conflict_policy: 'queue_first',
+      handoff_path: source.handoff_path || '',
+    },
+  };
+}
+
+export async function planWritebackCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const dayStamp = timestamp().slice(0, 10);
+
+  const sourceId = args['source-id'];
+  const sessionId = String(args['session-id'] || '');
+  let session = null;
+  if (sessionId) {
+    let state = { sessions: {} };
+    try { state = loadSessionState(root, vaultCfg); } catch (error) {
+      return done(args, { ok: false, command: 'plan-writeback', durable_write: false, error: error.message });
+    }
+    session = (state.sessions || {})[sessionId];
+    if (!session) return done(args, { ok: false, command: 'plan-writeback', durable_write: false, error: `unknown session "${sessionId}"` });
+  }
+
+  let envelope;
+  if (sourceId) {
+    const envRel = `${vaultCfg.raw_inbox_dir}/${sourceId}.json`;
+    envelope = readJsonSafe(path.join(root, envRel), null);
+    if (!envelope) return done(args, { ok: false, command: 'plan-writeback', durable_write: false, error: `Envelope not found: ${envRel}` });
+    if (session) {
+      envelope.session_id = sessionId;
+      envelope.session_scope = session.scope || '';
+      envelope.handoff_path = handoffPathFor(vaultCfg, sessionId, session);
+      if (!(envelope.area_candidates && envelope.area_candidates.length) && session.area) envelope.area_candidates = [session.area];
+    }
+  } else {
+    const bodyText = readArgInput(args, root);
+    if (!bodyText.trim()) {
+      return done(args, { ok: false, command: 'plan-writeback', durable_write: false, error: 'No input provided. Pass --source-id, --file, stdin, or positional text.' });
+    }
+    envelope = makeEnvelope(root, {
+      sourceId: args['dry-source-id'] || `planned-${dayStamp}`,
+      sourceType: args.type || 'memo',
+      title: args.title || firstLineTitle(bodyText, 'Untitled plan'),
+      text: bodyText,
+      status: 'planned',
+      overrides: {
+        area: args.area || (session && session.area),
+        sensitivity: args.sensitivity,
+        intent: args.intent,
+      },
+    }, { vaultCfg });
+    if (session) {
+      envelope.session_id = sessionId;
+      envelope.session_scope = session.scope || '';
+      envelope.handoff_path = handoffPathFor(vaultCfg, sessionId, session);
+    }
+  }
+
+  const plan = buildWritebackPlan(envelope, vaultCfg, dayStamp);
+  return done(args, { ok: true, command: 'plan-writeback', durable_write: false, ...plan });
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  if (!payload.ok) return { text: `# Writeback Plan\n\n- ${payload.error}` };
+  const lines = ['# Writeback Plan', '', `- Source ID: ${payload.source_id}`, `- Title: ${payload.title}`];
+  if (payload.session_id) lines.push(`- Session: ${payload.session_id}`);
+  lines.push(`- Scope: ${payload.scope}`);
+  lines.push(`- Status: ${payload.status}`);
+  if (payload.gates.length) {
+    lines.push('', '## Confirmation Gates', '');
+    for (const gate of payload.gates) lines.push(`- ${gate}`);
+  }
+  lines.push('', '## Targets', '');
+  for (const target of payload.targets) lines.push(`- ${target.layer}: ${target.action} -> ${target.path}`);
+  return { text: lines.join('\n') };
+}

package/src/core/queue.mjs

@@ -0,0 +1,62 @@
+// Read-only unified queue view command. Surfaces the central + per-area
+// writeback queues via queue_model. Never writes any queue. Flag surface mirrors
+// the vault tool so a vault shim is a pure passthrough.
+import { absPath } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { loadUnifiedQueue, losslessCheck } from './queue_model.mjs';
+
+export async function queueCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const unified = loadUnifiedQueue(root, vaultCfg);
+
+  let payload;
+  if (args['lossless-check']) {
+    payload = { ok: true, command: 'queue', durable_write: false, mode: 'lossless-check', ...losslessCheck(unified) };
+  } else if (args.stats) {
+    const byQueue = {};
+    const byStatus = {};
+    for (const r of unified.records) {
+      byQueue[r.queue] = (byQueue[r.queue] || 0) + 1;
+      byStatus[r.status] = (byStatus[r.status] || 0) + 1;
+    }
+    payload = { ok: true, command: 'queue', durable_write: false, mode: 'stats', total: unified.records.length, queues: unified.queues, by_queue: byQueue, by_status: byStatus };
+  } else {
+    let recs = unified.records;
+    if (args.queue) recs = recs.filter((r) => r.queue === String(args.queue));
+    if (args.status) recs = recs.filter((r) => r.status === String(args.status));
+    if (args.pending) recs = recs.filter((r) => r.status === 'pending');
+    payload = { ok: true, command: 'queue', durable_write: false, mode: 'list', count: recs.length, records: recs };
+  }
+
+  if (args.json) return { json: true, payload };
+  return { text: renderQueue(payload) };
+}
+
+function truncate(s, n) {
+  const value = String(s || '');
+  return value.length > n ? `${value.slice(0, n)}...` : value;
+}
+
+function renderQueue(res) {
+  if (res.mode === 'lossless-check') {
+    const lines = ['# Unified Queue Lossless Check', '', `- records: ${res.records}`, `- zero-loss (clean mapping): ${res.ok ? 'yes' : 'no'}`];
+    for (const l of res.leftovers) lines.push(`- UNMAPPED [${l.queue}] ${l.id}: ${l.unmapped_keys.join(', ')}`);
+    return lines.join('\n');
+  }
+  if (res.mode === 'stats') {
+    const lines = ['# Unified Queue Stats', '', `- total records: ${res.total}`];
+    for (const q of res.queues) {
+      lines.push(`- ${q.queue} (${q.format}): ${q.items} items from ${q.rows} rows${q.status_events != null ? `, ${q.status_events} status events` : ''}${q.metas != null ? `, ${q.metas} meta` : ''}`);
+    }
+    lines.push(`- by status: ${Object.entries(res.by_status).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+    return lines.join('\n');
+  }
+  const lines = [`# Unified Queue (${res.count})`, ''];
+  if (!res.records.length) return `${lines.join('\n')}\nNo matching queue records.`;
+  for (const r of res.records) {
+    lines.push(`- [${r.queue}] ${r.id} (${r.status}) area=${r.area || '-'} | ${truncate(r.title || r.summary, 90)}`);
+    if (r.status_history && r.status_history.length > 1) lines.push(`  history: ${r.status_history.map((h) => h.status).join(' -> ')}`);
+  }
+  return lines.join('\n');
+}

package/src/core/queue_archive.mjs

@@ -0,0 +1,87 @@
+// `queue-archive` command (W-B). Moves terminal writeback rows (compiled,
+// superseded, flushed, obsolete) out of the hot queue into an append-only archive
+// so the hot queue stays bounded to actionable (pending) work. Provenance is
+// preserved: archived rows carry an archived_at stamp and each source still has
+// its raw inbox envelope. The hot-queue rewrite re-reads inside the lock so a
+// concurrent append is never lost; the archive is appended first so a crash
+// leaves at worst a recoverable duplicate, never a lost row. Faithful port of the
+// vault neurain-queue-archive tool.
+import fs from 'node:fs';
+import path from 'node:path';
+import { absPath, ensureDir, timestamp } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { atomicWriteText, readJsonlRows, withFileLock } from './durable.mjs';
+
+const TERMINAL = new Set(['compiled', 'superseded', 'flushed', 'obsolete']);
+
+function countBy(list) {
+  return list.reduce((acc, row) => { acc[row.status] = (acc[row.status] || 0) + 1; return acc; }, {});
+}
+
+export async function queueArchiveCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const queueAbs = path.join(root, vaultCfg.writeback_queue);
+  const archiveRel = vaultCfg.writeback_queue_archive;
+  const archiveAbs = path.join(root, archiveRel);
+  const dryRun = Boolean(args['dry-run']);
+  const olderThanDays = args['older-than-days'] !== undefined ? Number(args['older-than-days']) : null;
+  const now = Date.now();
+
+  if (!fs.existsSync(queueAbs)) {
+    return done(args, { ok: true, command: 'queue-archive', durable_write: false, note: 'No queue file.', archived: 0, kept: 0, archive_path: archiveRel });
+  }
+
+  function rowAgeDays(row) {
+    const parsed = Date.parse(row.compiled_at || row.queued_at || '');
+    if (Number.isNaN(parsed)) return Infinity;
+    return (now - parsed) / (1000 * 60 * 60 * 24);
+  }
+  function isArchivable(row) {
+    if (!TERMINAL.has(row.status)) return false;
+    if (olderThanDays === null) return true;
+    return rowAgeDays(row) >= olderThanDays;
+  }
+
+  const rows = readJsonlRows(queueAbs);
+  const toArchive = rows.filter(isArchivable);
+  const toKeep = rows.filter((row) => !isArchivable(row));
+  const willWrite = !dryRun && toArchive.length > 0;
+
+  if (willWrite) {
+    withFileLock(queueAbs, () => {
+      const freshRows = readJsonlRows(queueAbs);
+      const freshArchive = freshRows.filter(isArchivable);
+      const freshKeep = freshRows.filter((row) => !isArchivable(row));
+      if (freshArchive.length === 0) return;
+      const stamped = freshArchive.map((row) => JSON.stringify({ ...row, archived_at: timestamp() }));
+      ensureDir(path.dirname(archiveAbs));
+      fs.appendFileSync(archiveAbs, `${stamped.join('\n')}\n`);
+      atomicWriteText(queueAbs, freshKeep.length ? `${freshKeep.map((row) => JSON.stringify(row)).join('\n')}\n` : '');
+    });
+  }
+
+  const payload = {
+    ok: true,
+    command: 'queue-archive',
+    durable_write: willWrite,
+    dry_run: dryRun,
+    hot_queue_before: rows.length,
+    hot_queue_after: toKeep.length,
+    archived: toArchive.length,
+    archive_path: archiveRel,
+    older_than_days: olderThanDays,
+    kept_status_breakdown: countBy(toKeep),
+    archived_status_breakdown: countBy(toArchive),
+  };
+  return done(args, payload);
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  const lines = ['# Queue Archive', ''];
+  lines.push(`- Dry run: ${payload.dry_run ? 'yes' : 'no'}`);
+  lines.push(`- Hot queue: ${payload.hot_queue_before ?? 0} -> ${payload.hot_queue_after ?? 0}`);
+  lines.push(`- Archived: ${payload.archived} to ${payload.archive_path}`);
+  return { text: lines.join('\n') };
+}

package/src/core/queue_model.mjs

@@ -0,0 +1,161 @@
+// Read-only unified queue model. Port of the vault queue-model: reads the central
+// flat writeback queue plus every per-area queue registered in the search index
+// registry (flat or event-sourced queue_item/queue_status/queue_meta) and folds
+// both into one canonical record set. Losslessness is by construction: every
+// source key is either mapped to a canonical field or retained in `extra`;
+// losslessCheck reports any unmapped key so a future write cutover can be proven
+// zero-loss. Strictly read-only; writes nothing.
+import path from 'node:path';
+import { readJsonl, readJsonSafe } from './vault_state.mjs';
+
+function normalizeFlatRow(row, queue) {
+  const extra = { ...row };
+  const take = (key) => {
+    const value = extra[key];
+    delete extra[key];
+    return value;
+  };
+  const areaCandidates = take('area_candidates') || [];
+  return {
+    queue,
+    format: 'flat',
+    id: take('source_id') || take('queue_id') || '',
+    status: take('status') || 'pending',
+    recorded_at: take('queued_at') || take('recorded_at') || '',
+    title: take('title') || '',
+    summary: take('summary') || '',
+    area: (Array.isArray(areaCandidates) ? areaCandidates[0] : areaCandidates) || (queue === 'root' ? '' : queue),
+    area_candidates: areaCandidates,
+    raw_path: take('raw_path') || '',
+    source_docs: take('source_docs') || [],
+    raw_input: take('raw_input') || '',
+    input_sha256: take('input_sha256') || '',
+    speed_policy: take('speed_policy') || '',
+    capture_id: take('capture_id') || '',
+    capture_title: take('capture_title') || '',
+    capture_envelope: take('capture_envelope') || null,
+    plan_summary: take('plan_summary') || null,
+    write_intent: take('write_intent') || '',
+    sensitivity: take('sensitivity') || '',
+    flush_level: take('flush_level') || '',
+    target_layer: take('target_layer') || '',
+    target_path: take('target_path') || '',
+    conflict_policy: take('conflict_policy') || '',
+    session_id: take('session_id') || '',
+    scope: take('scope') || '',
+    handoff_path: take('handoff_path') || '',
+    requires_user_decision: take('requires_user_decision') ?? false,
+    compiled_at: take('compiled_at') || '',
+    compiled_to: take('compiled_to') || '',
+    completed_at: take('completed_at') || '',
+    superseded_by: take('superseded_by') || '',
+    status_history: [],
+    extra,
+  };
+}
+
+function normalizeEventSourced(rows, queue) {
+  const items = new Map();
+  const statuses = new Map();
+  const metas = [];
+  for (const row of rows) {
+    if (row.record_type === 'queue_item' && row.queue_id) items.set(row.queue_id, row);
+    else if (row.record_type === 'queue_status' && row.queue_id) {
+      if (!statuses.has(row.queue_id)) statuses.set(row.queue_id, []);
+      statuses.get(row.queue_id).push(row);
+    } else metas.push(row);
+  }
+  const records = [];
+  let statusEvents = 0;
+  for (const [qid, item] of items) {
+    const extra = { ...item };
+    const take = (key) => {
+      const value = extra[key];
+      delete extra[key];
+      return value;
+    };
+    take('record_type');
+    const initialStatus = take('status') || 'pending';
+    const hist = (statuses.get(qid) || []).slice().sort((a, b) => String(a.recorded_at).localeCompare(String(b.recorded_at)));
+    statusEvents += hist.length;
+    records.push({
+      queue,
+      format: 'event-sourced',
+      id: take('queue_id') || qid,
+      status: hist.length ? hist[hist.length - 1].status : initialStatus,
+      recorded_at: take('recorded_at') || '',
+      title: take('capture_title') || '',
+      summary: take('summary') || '',
+      area: queue,
+      area_candidates: [queue],
+      raw_path: take('raw_path') || '',
+      source_docs: take('source_docs') || [],
+      raw_input: take('raw_input') || '',
+      input_sha256: take('input_sha256') || '',
+      speed_policy: take('speed_policy') || '',
+      capture_id: take('capture_id') || '',
+      capture_title: '',
+      capture_envelope: take('capture_envelope') || null,
+      plan_summary: take('plan_summary') || null,
+      write_intent: '',
+      sensitivity: '',
+      flush_level: '',
+      target_layer: '',
+      target_path: '',
+      conflict_policy: '',
+      session_id: '',
+      scope: '',
+      handoff_path: '',
+      requires_user_decision: false,
+      initial_status: initialStatus,
+      status_history: [
+        { recorded_at: item.recorded_at || '', status: initialStatus, note: 'queued' },
+        ...hist.map((h) => ({ recorded_at: h.recorded_at || '', status: h.status || '', note: h.note || '' })),
+      ],
+      extra,
+    });
+  }
+  return { records, metas, statusEvents };
+}
+
+export function loadUnifiedQueue(root, vaultCfg) {
+  const registry = readJsonSafe(path.join(root, vaultCfg.search_index_registry), { areas: {} });
+  const records = [];
+  const queues = [];
+  const metas = [];
+
+  const rootRows = readJsonl(path.join(root, vaultCfg.writeback_queue));
+  for (const row of rootRows) records.push(normalizeFlatRow(row, 'root'));
+  queues.push({ queue: 'root', path: vaultCfg.writeback_queue, rows: rootRows.length, items: rootRows.length, format: 'flat' });
+
+  for (const [area, entry] of Object.entries(registry.areas || {})) {
+    if (!entry || !entry.writeback_queue || !entry.area_root) continue;
+    const relPath = `${entry.area_root}/${entry.writeback_queue}`;
+    const rows = readJsonl(path.join(root, relPath));
+    const eventSourced = rows.some((r) => r && r.record_type);
+    if (eventSourced) {
+      const folded = normalizeEventSourced(rows, area);
+      for (const rec of folded.records) records.push(rec);
+      for (const meta of folded.metas) metas.push({ queue: area, ...meta });
+      queues.push({ queue: area, path: relPath, rows: rows.length, items: folded.records.length, status_events: folded.statusEvents, metas: folded.metas.length, format: 'event-sourced' });
+    } else {
+      for (const row of rows) records.push(normalizeFlatRow(row, area));
+      queues.push({ queue: area, path: relPath, rows: rows.length, items: rows.length, format: 'flat' });
+    }
+  }
+  return { records, queues, metas };
+}
+
+export function losslessCheck(unified) {
+  const leftovers = [];
+  for (const rec of unified.records) {
+    const keys = Object.keys(rec.extra || {});
+    if (keys.length) leftovers.push({ queue: rec.queue, id: rec.id, unmapped_keys: keys });
+  }
+  return {
+    ok: leftovers.length === 0,
+    records: unified.records.length,
+    meta_records: (unified.metas || []).length,
+    leftovers,
+  };
+}