neurain 0.1.0-alpha.0

package/src/core/review_queue.mjs

@@ -0,0 +1,131 @@
+// Read-only review desk. Port of the vault review-queue: groups pending
+// writeback-queue items into safe vs needs-confirmation, detects same-target
+// conflicts, and ranks deep-compile candidates from the source-digest manifest.
+// Private items never expose their file paths ([redacted:private], byte-identical
+// to the vault). Writes nothing.
+import path from 'node:path';
+import { absPath } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { readJsonl } from './vault_state.mjs';
+import { deepCompileCandidates } from './source_digest.mjs';
+
+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 targetKeyFor(item) {
+  return `${item.target_layer || inferTargetLayer(item)}:${item.target_path || ''}`;
+}
+
+function detectConflicts(items) {
+  const byTarget = new Map();
+  for (const item of items) {
+    if (!item.target_path) continue;
+    const key = targetKeyFor(item);
+    const rows = byTarget.get(key) || [];
+    rows.push(item);
+    byTarget.set(key, rows);
+  }
+  return [...byTarget.entries()]
+    .filter(([, rows]) => rows.length > 1)
+    .map(([target, rows]) => ({
+      target,
+      count: rows.length,
+      source_ids: rows.map((row) => row.source_id || row.queue_id || '').filter(Boolean),
+      policy: 'queue_first',
+      action: 'Ask user before applying any official update to this target.',
+    }));
+}
+
+function reviewReason(item, hasConflict) {
+  const reasons = [];
+  const targetLayer = item.target_layer || inferTargetLayer(item);
+  if (hasConflict) reasons.push('target conflict');
+  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 = []) {
+  const priv = item.sensitivity === 'private';
+  return {
+    source_id: item.source_id || '',
+    title: item.title || '',
+    session_id: item.session_id || '',
+    raw_path: priv ? '[redacted:private]' : (item.raw_path || ''),
+    target_layer: item.target_layer || inferTargetLayer(item),
+    target_path: priv ? '' : (item.target_path || ''),
+    sensitivity: item.sensitivity || 'internal',
+    flush_level: item.flush_level || inferFlushLevel(item),
+    reasons,
+  };
+}
+
+export async function reviewQueueCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  const sessionId = String(args['session-id'] || '');
+  const queueRel = String(args.queue || vaultCfg.writeback_queue);
+  const top = Number(args.top || 12);
+
+  const pending = readJsonl(path.join(root, queueRel)).filter((row) => {
+    if (!row || row.status !== 'pending') return false;
+    return !sessionId || row.session_id === sessionId;
+  });
+  const conflicts = detectConflicts(pending);
+  const conflictKeys = new Set(conflicts.map((c) => c.target));
+  const safe = [];
+  const needsConfirmation = [];
+  for (const item of pending) {
+    const reasons = reviewReason(item, conflictKeys.has(targetKeyFor(item)));
+    const summary = summarizeQueueItem(item, reasons);
+    (reasons.length === 0 ? safe : needsConfirmation).push(summary);
+  }
+  const candidates = deepCompileCandidates(root, vaultCfg, { top });
+
+  const payload = {
+    ok: true,
+    command: 'review-queue',
+    durable_write: false,
+    queue: queueRel,
+    manifest: args.manifest || vaultCfg.source_digest_manifest,
+    session_id: sessionId || null,
+    pending_count: pending.length,
+    safe_count: safe.length,
+    needs_confirmation_count: needsConfirmation.length,
+    conflict_count: conflicts.length,
+    deep_compile_candidate_count: candidates.length,
+    safe,
+    needs_confirmation: needsConfirmation,
+    conflicts,
+    deep_compile_candidates: candidates,
+    user_explanation: 'This is the review desk. Safe items can move through normal Standard review. Confirmation items need user approval. Deep Compile candidates are important raw sources worth reading more carefully before official memory changes.',
+  };
+  if (args.json) return { json: true, payload };
+  return {
+    text: [
+      '# Review Queue',
+      '',
+      `- Pending: ${payload.pending_count}`,
+      `- Safe: ${payload.safe_count}`,
+      `- Needs confirmation: ${payload.needs_confirmation_count}`,
+      `- Conflicts: ${payload.conflict_count}`,
+      `- Deep Compile candidates: ${payload.deep_compile_candidate_count}`,
+      '',
+      payload.user_explanation,
+    ].join('\n'),
+  };
+}

package/src/core/review_worker.mjs

@@ -0,0 +1,284 @@
+import { absPath, sha256 } from './fs.mjs';
+import { lessonCandidates } from './lessons.mjs';
+import { inferSensitivityFromPath } from './safety.mjs';
+import { buildWatchReport } from './watch.mjs';
+
+const REVIEW_EVENT_TYPES = new Set(['correction', 'review', 'rollback']);
+
+export async function reviewCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  if (args.apply || args.write || args.promote || args.daemon || args.follow) {
+    throw new Error('Public alpha supports review worker reports only. It cannot write, promote, follow, or run as a daemon.');
+  }
+  if (args['include-private']) {
+    throw new Error('Review worker reports are always private-clean. Use watch --include-private for local inspection only.');
+  }
+  const report = buildReviewWorkerReport(root, {
+    area: args.area || '',
+    top: Number(args.top || 10),
+    sinceMinutes: Number(args['since-minutes'] || 1440),
+  });
+  if (args.json) return { json: true, payload: report };
+  return {
+    text: [
+      '# Neurain review worker',
+      '',
+      `- Root: ${root}`,
+      `- Area: ${report.area || 'all'}`,
+      '- Durable write: no',
+      '- Model calls: no',
+      `- Review items: ${report.review_items.length}`,
+      `- Candidate proposals: ${report.candidate_proposals.length}`,
+      `- Blocked items: ${report.blocked_items.length}`,
+      '',
+      '## Suggested actions',
+      ...(report.suggested_actions.length ? report.suggested_actions.map((item) => `- [${item.priority}] ${item.title}`) : ['- none']),
+      '',
+      '## Candidate proposals',
+      ...(report.candidate_proposals.length ? report.candidate_proposals.map((item) => `- ${item.proposal_id}: ${item.title} (${item.decision})`) : ['- none']),
+    ].join('\n'),
+  };
+}
+
+export function buildReviewWorkerReport(root, {
+  area = '',
+  top = 10,
+  sinceMinutes = 1440,
+} = {}) {
+  const numericTop = Math.max(1, Math.min(Number(top || 10), 50));
+  const watch = buildWatchReport(root, {
+    area,
+    top: numericTop,
+    sinceMinutes,
+    pollOnce: true,
+    includePrivate: false,
+  });
+  const candidates = lessonCandidates(root, { limit: Math.min(numericTop, 10), area });
+  const candidateProposals = candidates.map((candidate) => proposalFromLessonCandidate(candidate));
+  const eventProposals = eventSequenceProposals(watch.recent_events, numericTop);
+  const reviewItems = [
+    ...watch.review_triggers.map((trigger) => reviewItemFromTrigger(trigger)),
+    ...candidateProposals.map((proposal) => reviewItemFromProposal(proposal)),
+    ...eventProposals.map((proposal) => reviewItemFromProposal(proposal)),
+  ];
+  const blockedItems = [
+    ...candidateProposals.filter((proposal) => proposal.decision === 'blocked'),
+    ...eventProposals.filter((proposal) => proposal.decision === 'blocked'),
+    ...unsafeWatchEvents(watch),
+  ];
+  const suggestedActions = suggestedActionsFor({ watch, candidateProposals, eventProposals, blockedItems });
+
+  const receipt = {
+    report_hash: sha256(stableJson({
+      watch: {
+        review_triggers: watch.review_triggers,
+        recent_events: watch.recent_events.map((event) => ({
+          event_id: event.event_id,
+          type: event.type,
+          redacted: event.redacted,
+          source_ids_withheld: event.source_ids_withheld,
+        })),
+      },
+      candidateProposals: candidateProposals.map((proposal) => proposal.proposal_id),
+      eventProposals: eventProposals.map((proposal) => proposal.proposal_id),
+    })),
+    source: 'deterministic-local-report',
+  };
+
+  return {
+    ok: true,
+    command: 'review',
+    root,
+    area: area || null,
+    durable_write: false,
+    model_calls: false,
+    external_tool_calls: false,
+    write_policy: 'read_only_review_report',
+    recursion_guard: {
+      enabled: true,
+      starts_nested_review_worker: false,
+      reason: 'review worker alpha reports only and performs no writes or model calls',
+    },
+    watch_report: watch,
+    review_items: reviewItems.slice(0, numericTop * 3),
+    candidate_proposals: candidateProposals,
+    event_sequence_proposals: eventProposals,
+    blocked_items: blockedItems,
+    suggested_actions: suggestedActions,
+    receipt,
+    next_step: suggestedActions.length
+      ? 'Review suggested actions manually. Durable promotion still requires an explicit CLI confirmation phrase.'
+      : 'No review-worker action needed from the current local signals.',
+  };
+}
+
+function proposalFromLessonCandidate(candidate) {
+  const privateSource = (candidate.source_ids || []).some((source) => inferSensitivityFromPath(source) === 'private');
+  const unsafe = !candidate.safety?.promotion_allowed || candidate.max_sensitivity === 'private' || privateSource;
+  const usefulness = usefulnessForCandidate(candidate);
+  const risk = unsafe ? 90 : candidate.scope !== 'global' ? 65 : 25;
+  const areaScoped = candidate.scope !== 'global';
+  return {
+    proposal_id: `review-proposal-${sha256(`candidate:${candidate.id}:${candidate.candidate_hash}`).slice(0, 12)}`,
+    kind: 'lesson_candidate',
+    title: candidate.title,
+    source_candidate_ids: [candidate.id],
+    source_event_ids: [],
+    source_paths: unsafe ? [] : candidate.source_ids || [],
+    source_paths_withheld: unsafe,
+    usefulness_score: usefulness,
+    risk_score: risk,
+    decision: unsafe ? 'blocked' : 'manual_review',
+    blocked_reason: unsafe ? blockedReason(candidate, privateSource) : null,
+    recommendation: unsafe
+      ? 'Do not promote. Sanitize or keep local/private until a human explicitly reclassifies it.'
+      : areaScoped
+        ? 'Manual review allowed as an area-local lesson. Do not promote globally without reclassifying the source.'
+        : 'Manual review allowed. Promotion still requires `neurain lessons promote ... --confirm "1건 저장 진행"`.',
+  };
+}
+
+function eventSequenceProposals(events, limit) {
+  const reviewEvents = events.filter((event) => REVIEW_EVENT_TYPES.has(event.type)).slice(0, limit);
+  return reviewEvents.map((event) => {
+    const blocked = event.redacted || event.source_ids_withheld || !event.safety?.cross_host_allowed;
+    return {
+      proposal_id: `review-proposal-${sha256(`event:${event.event_id}:${event.type}`).slice(0, 12)}`,
+      kind: 'event_sequence',
+      title: titleForEvent(event),
+      source_candidate_ids: [],
+      source_event_ids: [event.event_id],
+      source_paths: blocked ? [] : event.source_ids || [],
+      source_paths_withheld: blocked,
+      usefulness_score: event.type === 'correction' || event.type === 'rollback' ? 85 : 70,
+      risk_score: blocked ? 85 : 30,
+      decision: blocked ? 'blocked' : 'manual_review',
+      blocked_reason: blocked ? 'event is private, unsafe, or withheld from prompt context' : null,
+      recommendation: blocked
+        ? 'Keep this as a private review signal. Do not create a global lesson from it.'
+        : 'Review this event sequence for a possible lesson or capability routing hint.',
+    };
+  });
+}
+
+function reviewItemFromTrigger(trigger) {
+  return {
+    item_id: `review-item-${sha256(`trigger:${trigger.id}:${trigger.reason}`).slice(0, 12)}`,
+    kind: 'trigger',
+    priority: trigger.priority,
+    title: trigger.reason,
+    source_event_ids: trigger.source_event_ids || [],
+    source_candidate_ids: trigger.source_candidate_ids || [],
+    source_paths: trigger.source_paths || [],
+    source_paths_withheld: Boolean(trigger.source_paths_withheld),
+    decision: trigger.id === 'unsafe-events' || trigger.id === 'journal-integrity' ? 'manual_review_required' : 'manual_review',
+  };
+}
+
+function reviewItemFromProposal(proposal) {
+  return {
+    item_id: `review-item-${proposal.proposal_id.slice(-12)}`,
+    kind: proposal.kind,
+    priority: proposal.decision === 'blocked' ? 'high' : proposal.usefulness_score >= 80 ? 'medium' : 'low',
+    title: proposal.title,
+    source_event_ids: proposal.source_event_ids,
+    source_candidate_ids: proposal.source_candidate_ids,
+    source_paths: proposal.source_paths,
+    source_paths_withheld: Boolean(proposal.source_paths_withheld),
+    decision: proposal.decision,
+  };
+}
+
+function unsafeWatchEvents(watch) {
+  return watch.recent_events
+    .filter((event) => event.redacted || event.source_ids_withheld || !event.safety?.cross_host_allowed)
+    .map((event) => ({
+      proposal_id: `blocked-event-${sha256(event.event_id).slice(0, 12)}`,
+      kind: 'watch_event',
+      title: `${event.type} event withheld from prompt context`,
+      source_event_ids: [event.event_id],
+      source_candidate_ids: [],
+      source_paths: [],
+      source_paths_withheld: true,
+      usefulness_score: 50,
+      risk_score: 90,
+      decision: 'blocked',
+      blocked_reason: 'event is private, redacted, or not cross-host safe',
+      recommendation: 'Keep as private/local review signal only.',
+    }));
+}
+
+function suggestedActionsFor({ watch, candidateProposals, eventProposals, blockedItems }) {
+  const actions = [];
+  if (!watch.journal_integrity.ok) {
+    actions.push({
+      id: 'fix-journal-integrity',
+      priority: 'high',
+      title: 'Inspect journal integrity before trusting review output',
+      command: 'neurain journal verify <folder> --json',
+    });
+  }
+  if (blockedItems.length) {
+    actions.push({
+      id: 'review-blocked-private-or-unsafe-items',
+      priority: 'high',
+      title: `${blockedItems.length} blocked private or unsafe signal(s) need manual handling`,
+      command: 'neurain watch <folder> --poll-once --json',
+    });
+  }
+  const reviewableCandidates = candidateProposals.filter((proposal) => proposal.decision === 'manual_review');
+  if (reviewableCandidates.length) {
+    actions.push({
+      id: 'review-lesson-candidates',
+      priority: 'medium',
+      title: `${reviewableCandidates.length} lesson candidate proposal(s) are ready for manual review`,
+      command: 'neurain lessons candidates <folder> --json',
+    });
+  }
+  const reviewableEvents = eventProposals.filter((proposal) => proposal.decision === 'manual_review');
+  if (reviewableEvents.length) {
+    actions.push({
+      id: 'review-event-sequences',
+      priority: 'medium',
+      title: `${reviewableEvents.length} event-derived proposal(s) may become lessons or routing hints`,
+      command: 'neurain review <folder> --json',
+    });
+  }
+  if (!actions.length && watch.review_triggers.length) {
+    actions.push({
+      id: 'inspect-watch-report',
+      priority: 'low',
+      title: 'Inspect watch report for low-priority local changes',
+      command: 'neurain watch <folder> --poll-once --json',
+    });
+  }
+  return actions;
+}
+
+function usefulnessForCandidate(candidate) {
+  if (candidate.lesson_type === 'verification') return 85;
+  if (candidate.lesson_type === 'safety') return 80;
+  if (candidate.lesson_type === 'tool_usage') return 75;
+  return 70;
+}
+
+function blockedReason(candidate, privateSource) {
+  if (candidate.max_sensitivity === 'private' || privateSource) return 'candidate is private or derived from a private path';
+  if (!candidate.safety?.promotion_allowed) return 'candidate failed safety gate';
+  if (candidate.scope !== 'global') return 'candidate is area-scoped and cannot become a global lesson automatically';
+  return 'candidate is blocked by review policy';
+}
+
+function titleForEvent(event) {
+  if (event.type === 'correction') return 'Review repeated correction for a possible lesson';
+  if (event.type === 'rollback') return 'Review rollback event for a safety lesson';
+  return 'Review event sequence for possible workflow improvement';
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/src/core/route.mjs

@@ -0,0 +1,73 @@
+// `route` command (W-B, read-only). Classifies source text into area / domain /
+// entity candidates, sensitivity, write intent, and a requires-user-decision
+// flag, optionally enriched with a session's scope + handoff path. Writes nothing.
+// Faithful port of the vault neurain-route tool; the route shape comes from the
+// shared classify core so route, plan-writeback, and capture stay consistent.
+import { absPath } from './fs.mjs';
+import { vaultConfig } from './config.mjs';
+import { loadSessionState } from './vault_state.mjs';
+import { classifyText, firstLineTitle, normalizeAreaId } from './classify.mjs';
+import { readArgInput } from './envelope.mjs';
+
+function handoffPathFor(vaultCfg, sessionId, session) {
+  return (session && session.handoff_path) || `${vaultCfg.session_handoff_dir}/${sessionId}.md`;
+}
+
+export async function routeCommand(args) {
+  const root = absPath(args._[0] || args.root || process.cwd());
+  const vaultCfg = vaultConfig(root);
+  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: 'route', durable_write: false, error: error.message });
+    }
+    session = (state.sessions || {})[sessionId];
+    if (!session) return done(args, { ok: false, command: 'route', durable_write: false, error: `unknown session "${sessionId}"` });
+  }
+
+  const text = readArgInput(args, root);
+  if (!text.trim()) {
+    return done(args, { ok: false, command: 'route', durable_write: false, error: 'No input provided. Pass --text, positional text, or --file.' });
+  }
+
+  const route = classifyText(root, text, {
+    area: normalizeAreaId(root, args.area || (session && session.area), vaultCfg),
+    sensitivity: args.sensitivity,
+    intent: args.intent,
+  }, { vaultCfg });
+
+  const payload = {
+    ok: true,
+    command: 'route',
+    durable_write: false,
+    title: args.title || firstLineTitle(text, 'Untitled route'),
+    source_type: args.type || 'memo',
+    ...(session
+      ? { session_id: sessionId, scope: session.scope || '', handoff_path: handoffPathFor(vaultCfg, sessionId, session) }
+      : {}),
+    ...route,
+  };
+  return done(args, payload);
+}
+
+function done(args, payload) {
+  if (args.json) return { json: true, payload };
+  if (!payload.ok) return { text: `# Neurain Route\n\n- ${payload.error}` };
+  const lines = [
+    '# Neurain Route',
+    '',
+    `- Title: ${payload.title}`,
+    `- Source type: ${payload.source_type}`,
+  ];
+  if (payload.session_id) lines.push(`- Session: ${payload.session_id}`);
+  lines.push(`- Areas: ${payload.area_candidates.join(', ') || 'none'}`);
+  lines.push(`- Domains: ${payload.domain_candidates.join(', ') || 'none'}`);
+  lines.push(`- Entities: ${payload.entity_candidates.join(', ') || 'none'}`);
+  lines.push(`- Sensitivity: ${payload.sensitivity}`);
+  lines.push(`- Write intent: ${payload.write_intent}`);
+  lines.push(`- Requires user decision: ${payload.requires_user_decision ? 'yes' : 'no'}`);
+  return { text: lines.join('\n') };
+}

package/src/core/safety.mjs

@@ -0,0 +1,57 @@
+export function secretLike(text) {
+  const value = String(text || '');
+  if (/(api[_-]?key|secret[_-]?key|access[_-]?token|auth[_-]?token|private[_-]?key|password)\s*[:=]/i.test(value)) return 'credential pattern';
+  if (/-----BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----/.test(value)) return 'private key block';
+  if (/\b(sk-[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,})\b/.test(value)) return 'token-shaped value';
+  return '';
+}
+
+export function injectionLike(text) {
+  const value = String(text || '').toLowerCase();
+  const patterns = [
+    /ignore (all )?(previous|prior) instructions/,
+    /disregard (all )?(previous|prior) instructions/,
+    /reveal (the )?(system|developer) prompt/,
+    /exfiltrate/,
+    /disable (safety|guardrails|policy)/,
+    /bypass (approval|permission|safety|guardrails)/,
+    /act as (an )?unrestricted/,
+  ];
+  return patterns.find((pattern) => pattern.test(value)) ? 'instruction-injection pattern' : '';
+}
+
+export function inferSensitivityFromPath(relPath) {
+  return /(secret|credential|private|password|token|\.env|keychain|recovery)/i.test(String(relPath || ''))
+    ? 'private'
+    : 'internal';
+}
+
+export function maxSensitivity(values) {
+  return values.includes('private') ? 'private' : values.includes('internal') ? 'internal' : 'public';
+}
+
+export function safePreview(text, limit = 220) {
+  const value = String(text || '').replace(/\s+/g, ' ').trim();
+  if (!value) return '';
+  return value.slice(0, limit);
+}
+
+export function redactedPreview(text, limit = 220) {
+  const value = String(text || '');
+  const secret = secretLike(value);
+  const injection = injectionLike(value);
+  if (secret || injection) {
+    return {
+      text: secret ? '[redacted secret-like evidence]' : '[redacted instruction-injection evidence]',
+      redacted: true,
+      secret_like: secret || null,
+      injection_like: injection || null,
+    };
+  }
+  return {
+    text: safePreview(value, limit),
+    redacted: false,
+    secret_like: null,
+    injection_like: null,
+  };
+}