@mindrian_os/cli 1.13.0-beta.10 → 1.13.0-beta.44

package/lib/core/brain-derivation.cjs

@@ -1,580 +0,0 @@
-'use strict';
-
-/*
- * Copyright (c) 2026 Mindrian. BSL 1.1.
- *
- * Phase 90-01 Task 2 -- Brain derivation core
- * ===========================================
- * Single entry point deriveSection(roomPath, section, options) reads
- * the Phase 88 triple, builds Canon-Part-8-safe Brain query context
- * (generic handles ONLY), invokes Brain via brain-client.cjs for each
- * of the 9 optional BRAIN.md sections, assembles the authored markdown,
- * gates through Plan 90-00 validateSchema, and atomically writes the
- * section's BRAIN.md using the Phase 88-04-B tmp + fsync + rename
- * pattern.
- *
- * The LOAD-BEARING Canon Part 8 chokepoint is buildBrainQueryContext.
- * It is the ONLY function in this module that touches user-specific
- * triple fields, and it strips every touched field to an allow-list
- * scalar BEFORE any prompt builder or Brain call sees the context.
- * Every Brain query is then validated a second time through the
- * prompt-builder allow-list schema (lib/core/brain-derivation-prompts
- * .cjs validateCtx) before reaching the Brain.
- *
- * Graceful failure:
- *   - brain-client.isAvailable() === false -> reason:'brain_unavailable'
- *   - triple.reasoning.exists === false   -> reason:'triple_incomplete'
- *   - brain-client throws                 -> reason:'derivation_timeout' |
- *                                            'rate_limited' | 'derivation_error'
- *   - schema gate rejects assembly        -> success:false, violations[],
- *                                            tmpfile cleaned
- *   - writeLock contention                -> reason:'concurrent_write'
- *   - filesystem EACCES / ENOENT          -> reason:'fs_error'
- *   - deriveSection NEVER throws; every path returns a result object.
- *
- * Pure CJS, node built-ins only, zero npm deps. Three-surface safe
- * (CLI + Desktop MCP + Cowork; no surface-specific code).
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-
-const folderMemory = require('./folder-memory.cjs');
-const brainClient = require('./brain-client.cjs');
-const schemaValidator = require('./brain-md-schema.cjs');
-const prompts = require('./brain-derivation-prompts.cjs');
-
-// Phase 90-06 cross-room aggregator. Lazy-loaded inside deriveSection so
-// the top-level require graph stays minimal when cross_room_scan is
-// false (the default). The aggregator is Canon Part 8 safe by
-// construction: four enforcement layers (ALLOWED_ROOT scope, GUARDRAIL.md
-// sealed-room skip, per-room brain_cross_room:false opt-out, and
-// sanitizeDetailScalar + JSON.stringify last-line-of-defense audit).
-// See lib/core/cross-room-aggregator.cjs for the full contract.
-// (cross_room_scan option surfaces here; aggregator call is wired below)
-
-// ---------- Frozen constants ----------
-
-// Section heading -> prompt builder mapping. Order matters: this is the
-// canonical emission order inside BRAIN.md body.
-const SECTION_BUILDERS = Object.freeze([
-  { heading: 'Pattern Matches',                     builder: 'buildPatternMatchesQuery',                     mode: 'query' },
-  { heading: 'Cross-Domain Analogies',              builder: 'buildCrossDomainAnalogiesQuery',               mode: 'search' },
-  { heading: 'Wicked Indicators',                   builder: 'buildWickedIndicatorsQuery',                   mode: 'query' },
-  { heading: 'Unfilled Opportunity Matches',        builder: 'buildUnfilledOpportunityMatchesQuery',         mode: 'query' },
-  { heading: 'Framework Chain Predictions',         builder: 'buildFrameworkChainPredictionsQuery',          mode: 'query' },
-  { heading: 'Assessment Thinking Chain Position',  builder: 'buildAssessmentThinkingChainPositionQuery',    mode: 'query' },
-  { heading: 'ProblemType Classification',          builder: 'buildProblemTypeClassificationQuery',          mode: 'query' },
-  { heading: 'Flagged Contradictions (cross-room)', builder: 'buildFlaggedContradictionsXroomQuery',         mode: 'query' },
-  { heading: 'HSI Signals',                         builder: 'buildHsiSignalsQuery',                         mode: 'query' },
-]);
-
-// SHA256 of empty string is the deterministic sentinel used when the
-// governing_thought field is null / empty. It is parseable by downstream
-// validators and provides a stable anchor for change detection.
-const EMPTY_SHA256 = 'sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
-
-// ---------- Canon Part 8 CHOKEPOINT: buildBrainQueryContext ----------
-//
-// This function is the ONLY place in the module where triple fields
-// like reasoning.governing_thought, room.identity_text, and
-// reasoning.decision_log are touched. Everything leaving this function
-// is either:
-//   - a sha256 hash of a potentially-sensitive string
-//   - an integer scalar (arguments_count, artifact_count)
-//   - a float scalar in [0,1] (reasoning_health_score, evidence_density,
-//     completeness_score)
-//   - a derived enum from a frozen vocabulary (UDP/IDP/WDP, Simple/
-//     Complex/Wicked, phase indicator)
-//   - the section slug (structural folder name; user-chosen but
-//     slug-safe and never carries artifact content)
-//
-// No user-typed prose, personal names, meeting fragments, or artifact
-// bodies can pass this boundary.
-
-function buildBrainQueryContext(triple, sectionSlug) {
-  if (!triple || typeof triple !== 'object') return null;
-  if (!triple.reasoning || triple.reasoning.exists !== true) return null;
-
-  const reasoning = triple.reasoning;
-  const state = triple.state || {};
-
-  // Sha256 hash of governing_thought (normalize NFC so identical prose
-  // across Unicode normalizations yields the same hash).
-  const gt = reasoning.governing_thought == null ? '' : String(reasoning.governing_thought);
-  const gtHash = 'sha256:' + crypto.createHash('sha256').update(gt.normalize('NFC')).digest('hex');
-
-  // Derived classification.
-  const problemType = classifyProblemType(triple);
-  const complexity = deriveComplexity(triple);
-  const phaseIndicator = derivePhaseIndicator(triple);
-
-  // Allow-list scalars.
-  const argsCount = Number.isFinite(reasoning.arguments_count) ? Math.max(0, Math.floor(reasoning.arguments_count)) : 0;
-  const evDensity = clamp01(reasoning.evidence_density, 0);
-  const rhs = clamp01(reasoning.reasoning_health_score, 0);
-  const meceStatus = mapMeceStatus(reasoning.mece_status);
-  // Structural section slug only. Defensive slug cleaner: keep
-  // [a-z0-9_-] after lowercasing; fallback to 'unknown'.
-  const slug = (sectionSlug || '').toString().toLowerCase()
-    .replace(/[^a-z0-9_-]/g, '-')
-    .replace(/^[^a-z0-9]+/, '')
-    .slice(0, 64);
-  const safeSlug = /^[a-z0-9][a-z0-9_-]{0,63}$/.test(slug) ? slug : 'unknown';
-
-  // Reverse-salient signal is a scalar flag: present iff STATE.md says so
-  // (future Phase 89 integration). Today we default false.
-  const rsPresent = !!(state && state.reverse_salient_present === true);
-
-  return {
-    section_slug: safeSlug,
-    problem_type: problemType,
-    complexity: complexity,
-    phase_indicator: phaseIndicator,
-    reasoning_health_score: rhs,
-    arguments_count: argsCount,
-    mece_status: meceStatus,
-    evidence_density: evDensity,
-    governing_thought_hash: gtHash,
-    reverse_salient_present: rsPresent,
-  };
-}
-
-// ---------- Derivation helpers (frozen enum mappings) ----------
-
-function clamp01(v, fallback) {
-  const n = Number(v);
-  if (!Number.isFinite(n)) return Number(fallback) || 0;
-  if (n < 0) return 0;
-  if (n > 1) return 1;
-  return n;
-}
-
-function mapMeceStatus(raw) {
-  if (raw === 'pass' || raw === 'warn' || raw === 'fail') return raw;
-  // Legacy MINTO files may carry boolean-like or capitalized values.
-  if (raw === true || raw === 'ok' || raw === 'Pass') return 'pass';
-  if (raw === false || raw === 'fail' || raw === 'Fail') return 'fail';
-  return 'warn';
-}
-
-/**
- * classifyProblemType(triple) -> 'UDP' | 'IDP' | 'WDP'
- *
- * Frozen mapping derived from triple shape. No user strings are read:
- * this function converts the governing_thought field to a boolean
- * existence flag at the very first line and never touches its content.
- * The conversion is the ONLY place outside buildBrainQueryContext that
- * reads the field, and it reads length/null only -- a scalar signal
- * that satisfies Canon Part 8.
- *
- * - UDP (Undefined Problem): governing_thought missing OR mece fail with
- *   arguments_count < 2.
- * - WDP (Well-Defined Problem): mece pass AND arguments_count >= 4 AND
- *   evidence_density >= 0.35.
- * - IDP (Ill-Defined Problem): default (mece warn OR arguments_count in
- *   [2, 3] OR evidence_density < 0.35).
- */
-function classifyProblemType(triple) {
-  if (!triple || !triple.reasoning) return 'UDP';
-  const r = triple.reasoning;
-  // Scalar extraction: existence flag ONLY. Never store or forward the
-  // raw governing_thought value.
-  const hasGoverningThought = r.governing_thought != null &&
-    typeof r.governing_thought === 'string' &&
-    r.governing_thought.length > 0;
-  const mece = mapMeceStatus(r.mece_status);
-  const args = Number.isFinite(r.arguments_count) ? r.arguments_count : 0;
-  const ev = clamp01(r.evidence_density, 0);
-  if (!hasGoverningThought) return 'UDP';
-  if (mece === 'fail' && args < 2) return 'UDP';
-  if (mece === 'pass' && args >= 4 && ev >= 0.35) return 'WDP';
-  return 'IDP';
-}
-
-/**
- * deriveComplexity(triple) -> 'Simple' | 'Complex' | 'Wicked'
- *
- * Derived from reasoning_health_score + flagged-weaknesses count +
- * stale reason. Scalar thresholds, no string content read.
- */
-function deriveComplexity(triple) {
-  if (!triple || !triple.reasoning) return 'Simple';
-  const r = triple.reasoning;
-  const rhs = clamp01(r.reasoning_health_score, 0);
-  const weaknessesCount = Array.isArray(r.flagged_weaknesses) ? r.flagged_weaknesses.length : 0;
-  if (rhs >= 0.75 && weaknessesCount <= 1) return 'Simple';
-  if (rhs < 0.4 || weaknessesCount >= 4) return 'Wicked';
-  return 'Complex';
-}
-
-/**
- * derivePhaseIndicator(triple) -> enum
- *
- * Mapping from completeness_score + artifact_count + stale reason. Uses
- * only scalars from STATE.md / MINTO.md frontmatter.
- */
-function derivePhaseIndicator(triple) {
-  if (!triple || !triple.state) return 'unknown';
-  const s = triple.state;
-  const c = clamp01(s.completeness_score, 0);
-  const ac = Number.isFinite(s.artifact_count) ? s.artifact_count : 0;
-  if (ac === 0 && c < 0.1) return 'discovery';
-  if (c < 0.4) return 'formulation';
-  if (c < 0.8) return 'validation';
-  return 'scaling';
-}
-
-// ---------- Atomic write helpers (88-04-B pattern) ----------
-
-function tmpFileName(basePath) {
-  // BRAIN.md.tmp.<random>.brain matches the pattern asserted in Test 15.
-  const rand = Math.random().toString(36).slice(2) + Date.now().toString(36);
-  return basePath + '.tmp.' + rand + '.brain';
-}
-
-async function atomicWriteBrainMd(sectionPath, assembledBody, force_bad_staleness) {
-  const finalPath = path.join(sectionPath, 'BRAIN.md');
-  const tmpPath = tmpFileName(finalPath);
-  let fd = null;
-  try {
-    // Write with exclusive create (wx) so we catch concurrent writers.
-    fd = fs.openSync(tmpPath, 'wx');
-    // For the Test 6 schema-gate rejection path, inject an ERROR-severity
-    // schema violation by removing the required `author` field. This branch
-    // is never exercised in production.
-    const finalBody = force_bad_staleness
-      ? assembledBody.replace(/^author: .+\r?\n/m, '')
-      : assembledBody;
-    fs.writeFileSync(fd, finalBody);
-    fs.fsyncSync(fd);
-    fs.closeSync(fd);
-    fd = null;
-
-    // Validate before rename.
-    const result = schemaValidator.validateSchema(tmpPath);
-    const hardErrors = (result.violations || []).filter(function (v) {
-      return v.severity === schemaValidator.SEVERITY.ERROR ||
-             v.severity === schemaValidator.SEVERITY.CRITICAL;
-    });
-    if (hardErrors.length > 0) {
-      // Abort. Do NOT rename. Clean tmpfile.
-      try { fs.unlinkSync(tmpPath); } catch (_e) { /* best effort */ }
-      return { success: false, violations: result.violations, severity: result.severity };
-    }
-
-    // Atomic rename.
-    fs.renameSync(tmpPath, finalPath);
-    return { success: true, brain_md_path: finalPath, violations: result.violations || [] };
-  } catch (err) {
-    // On any failure, close + unlink tmpfile best-effort.
-    try { if (fd !== null) fs.closeSync(fd); } catch (_e) { /* best effort */ }
-    try { fs.unlinkSync(tmpPath); } catch (_e) { /* best effort */ }
-    return { success: false, violations: [], severity: null, fs_error: String(err && err.message) };
-  }
-}
-
-// ---------- Assembler ----------
-
-function assembleBrainMd(frontmatter, sectionResults) {
-  const fmLines = ['---'];
-  for (const k of Object.keys(frontmatter)) {
-    const v = frontmatter[k];
-    if (v === null) {
-      fmLines.push(k + ': null');
-    } else if (typeof v === 'number' || typeof v === 'boolean') {
-      fmLines.push(k + ': ' + v);
-    } else {
-      // Quote strings (simple dialect: no embedded quotes in our controlled
-      // scalars). We sanitize by stripping quote characters defensively.
-      const s = String(v).replace(/["'`]/g, '');
-      fmLines.push(k + ': "' + s + '"');
-    }
-  }
-  fmLines.push('---');
-  fmLines.push('');
-
-  const bodyLines = [];
-  for (const sec of SECTION_BUILDERS) {
-    bodyLines.push('## ' + sec.heading);
-    const entry = sectionResults[sec.heading];
-    if (!entry || entry.skipped) {
-      bodyLines.push('(no signal -- skipped)');
-    } else if (entry.error) {
-      bodyLines.push('(no signal -- ' + entry.error + ')');
-    } else if (entry.empty) {
-      bodyLines.push('(no signal)');
-    } else if (entry.text) {
-      bodyLines.push(entry.text);
-    } else {
-      bodyLines.push('(no signal)');
-    }
-    bodyLines.push('');
-  }
-  return fmLines.join('\n') + '\n' + bodyLines.join('\n') + '\n';
-}
-
-function renderRecords(result) {
-  if (result == null) return { empty: true };
-  if (Array.isArray(result.records)) {
-    if (result.records.length === 0) return { empty: true };
-    const lines = [];
-    for (const rec of result.records.slice(0, 5)) {
-      const name = rec.name || rec.framework || rec.indicator || rec.opportunity || rec.level || rec.from_framework || rec.problem_type || rec[0] || 'unnamed';
-      lines.push('- ' + String(name).slice(0, 160));
-    }
-    return { text: lines.join('\n') };
-  }
-  if (Array.isArray(result.matches)) {
-    if (result.matches.length === 0) return { empty: true };
-    const lines = [];
-    for (const m of result.matches.slice(0, 5)) {
-      const t = m.title || m.name || JSON.stringify(m).slice(0, 120);
-      lines.push('- ' + String(t).slice(0, 160));
-    }
-    return { text: lines.join('\n') };
-  }
-  return { empty: true };
-}
-
-// ---------- Main entry: deriveSection ----------
-
-/**
- * deriveSection(roomPath, section, options)
- *   -> Promise<{success, brain_md_path?, violations[], cost_tokens, reason?, dry_run?, would_query?}>
- *
- * NEVER throws. Every failure mode becomes a structured result.
- */
-async function deriveSection(roomPath, section, options) {
-  options = options || {};
-  const result = {
-    success: false,
-    violations: [],
-    cost_tokens: 0,
-  };
-
-  // Defensive arg handling: malformed inputs return a structured failure.
-  let sectionPath;
-  try {
-    if (typeof roomPath !== 'string' || typeof section !== 'string' ||
-        roomPath.length === 0 || section.length === 0) {
-      result.reason = 'invalid_args';
-      return result;
-    }
-    sectionPath = path.join(roomPath, section);
-  } catch (_e) {
-    result.reason = 'invalid_args';
-    return result;
-  }
-
-  // Dry-run shortcut: no Brain queries, no write.
-  if (options.dry_run === true) {
-    result.success = true;
-    result.dry_run = true;
-    const howMany = Array.isArray(options.only_sections) && options.only_sections.length > 0
-      ? options.only_sections.length
-      : SECTION_BUILDERS.length;
-    result.would_query = howMany;
-    return result;
-  }
-
-  // Brain availability gate.
-  try {
-    if (!brainClient.isAvailable()) {
-      result.reason = 'brain_unavailable';
-      return result;
-    }
-  } catch (_e) {
-    result.reason = 'brain_unavailable';
-    return result;
-  }
-
-  // Read the triple.
-  let triple;
-  try {
-    triple = folderMemory.readTriple(sectionPath);
-  } catch (_e) {
-    result.reason = 'triple_read_error';
-    return result;
-  }
-
-  if (!triple || !triple.reasoning || triple.reasoning.exists !== true) {
-    result.reason = 'triple_incomplete';
-    return result;
-  }
-
-  // Canon Part 8 chokepoint.
-  const ctx = buildBrainQueryContext(triple, section);
-  if (!ctx) {
-    result.reason = 'ctx_build_failed';
-    return result;
-  }
-
-  // Fetch Brain graph version ONCE.
-  let brainGraphVersion = 0;
-  try {
-    const sch = await brainClient.schema();
-    if (sch && typeof sch.brain_graph_version === 'number') {
-      brainGraphVersion = sch.brain_graph_version;
-    } else if (sch && sch.brain_graph_version != null) {
-      brainGraphVersion = Number(sch.brain_graph_version) || 0;
-    }
-  } catch (err) {
-    result.reason = categorizeError(err);
-    return result;
-  }
-
-  ctx.brain_graph_version = brainGraphVersion;
-
-  // Decide which sections to query.
-  const onlySections = Array.isArray(options.only_sections) && options.only_sections.length > 0
-    ? new Set(options.only_sections)
-    : null;
-
-  // Fire queries. First error wins; subsequent sections are skipped and
-  // the function returns a structured failure with tmpfile cleanup.
-  const sectionResults = {};
-  let tokens = 0;
-  let firstError = null;
-
-  for (const sec of SECTION_BUILDERS) {
-    if (onlySections && !onlySections.has(sec.heading)) {
-      sectionResults[sec.heading] = { skipped: true };
-      continue;
-    }
-    if (firstError) {
-      sectionResults[sec.heading] = { skipped: true };
-      continue;
-    }
-    let query;
-    try {
-      query = prompts[sec.builder](ctx);
-    } catch (err) {
-      // Builder-side allow-list violation. This is a Canon Part 8 internal
-      // breach: abort immediately with a clear reason.
-      firstError = { reason: 'ctx_build_failed', message: String(err && err.message) };
-      sectionResults[sec.heading] = { error: 'ctx-violation' };
-      continue;
-    }
-    if (query == null) {
-      // Stub or inapplicable builder.
-      sectionResults[sec.heading] = { empty: true };
-      continue;
-    }
-    try {
-      let res;
-      if (sec.mode === 'search') {
-        res = await brainClient.search(query, { topK: 5 });
-      } else {
-        res = await brainClient.query(query);
-      }
-      sectionResults[sec.heading] = renderRecords(res);
-      // Cost estimate: conservative 60 tokens per call.
-      tokens += 60;
-    } catch (err) {
-      firstError = { reason: categorizeError(err), message: String(err && err.message) };
-      sectionResults[sec.heading] = { error: 'brain-error' };
-    }
-  }
-
-  if (firstError) {
-    result.reason = firstError.reason;
-    result.cost_tokens = tokens;
-    return result;
-  }
-
-  // Assemble frontmatter.
-  const frontmatter = {
-    section: ctx.section_slug,
-    brain_generated_at: new Date().toISOString(),
-    brain_graph_version: brainGraphVersion || 0,
-    governing_thought_hash: ctx.governing_thought_hash || EMPTY_SHA256,
-    staleness: schemaValidator.STALENESS.FRESH,
-    author: 'brain',
-    stale_reason: null,
-    prompt_version: prompts.PROMPT_VERSION.value,
-    cost_tokens: tokens,
-    brain_query_count: SECTION_BUILDERS.reduce(function (n, sec) {
-      return sectionResults[sec.heading] && !sectionResults[sec.heading].skipped && !sectionResults[sec.heading].empty ? n + 1 : n;
-    }, 0),
-  };
-
-  // Phase 90-06 cross_room_scan hook: when opted in at call time, run
-  // the cross-room aggregator after local derivation and overwrite the
-  // 'Flagged Contradictions (cross-room)' section body with the
-  // structural-only rendering. Canon Part 8 is enforced at four layers
-  // inside the aggregator (ALLOWED_ROOT scope + GUARDRAIL.md sealed-room
-  // + per-room opt-out + sanitizeDetailScalar / JSON.stringify audit).
-  // Default off; opt-in per call.
-  if (options.cross_room_scan === true) {
-    try {
-      const xroom = require('./cross-room-aggregator.cjs');
-      const xroomResult = await xroom.aggregateContradictions(roomPath, {
-        opt_in: true,
-        max_rooms: Number.isFinite(options.cross_room_max_rooms) ? options.cross_room_max_rooms : 10,
-        per_room_timeout_ms: Number.isFinite(options.cross_room_timeout_ms) ? options.cross_room_timeout_ms : 300,
-      });
-      const xroomBody = xroom.renderCrossRoomSection(xroomResult);
-      sectionResults['Flagged Contradictions (cross-room)'] = { text: xroomBody };
-    } catch (_e) {
-      // Aggregator NEVER throws under normal conditions; any failure
-      // here is catastrophic. Leave the section as the upstream Brain
-      // query output (typically '(no signal)' since the stub builder
-      // returns null).
-    }
-  }
-
-  const body = assembleBrainMd(frontmatter, sectionResults);
-
-  // Atomic write + schema gate. Test 6 forces bad staleness through
-  // _test_force_bad_staleness to exercise the rejection branch.
-  const writeOut = await atomicWriteBrainMd(
-    sectionPath,
-    body,
-    options._test_force_bad_staleness === true
-  );
-
-  if (!writeOut.success) {
-    result.violations = writeOut.violations || [];
-    result.reason = writeOut.fs_error ? 'fs_error' : 'schema_rejected';
-    result.cost_tokens = tokens;
-    return result;
-  }
-
-  result.success = true;
-  result.brain_md_path = writeOut.brain_md_path;
-  result.violations = writeOut.violations || [];
-  result.cost_tokens = tokens;
-  return result;
-}
-
-// ---------- Error categorizer ----------
-
-function categorizeError(err) {
-  const msg = (err && err.message ? err.message : String(err || '')).toLowerCase();
-  if (/timeout|etimedout|timed out/.test(msg)) return 'derivation_timeout';
-  if (/rate[_\s-]?limited|429/.test(msg)) return 'rate_limited';
-  if (/auth|401|unauthorized|invalid_key/.test(msg)) return 'auth_failed';
-  return 'derivation_error';
-}
-
-// ---------- Exports ----------
-
-module.exports = {
-  deriveSection: deriveSection,
-  buildBrainQueryContext: buildBrainQueryContext,
-  classifyProblemType: classifyProblemType,
-  derivePhaseIndicator: derivePhaseIndicator,
-  deriveComplexity: deriveComplexity,
-  // Frozen section registry so downstream plans (90-05, 90-07) can iterate.
-  SECTION_BUILDERS: SECTION_BUILDERS,
-  EMPTY_SHA256: EMPTY_SHA256,
-  // Test surface: not part of the public API.
-  _test: Object.freeze({
-    atomicWriteBrainMd: atomicWriteBrainMd,
-    assembleBrainMd: assembleBrainMd,
-    renderRecords: renderRecords,
-    categorizeError: categorizeError,
-  }),
-};