kenaz 0.3.10 → 0.3.12

package/core/.formation/tools/post-complete/health.js

@@ -1,464 +0,0 @@
-/**
-// D.4 runtime validation ??TASK_1214
- * HEALTH_AND_GUARDIAN ??extracted from post-complete.js (D.4 refactor)
- *
- * Loop config reading, Synapse health measurement, health snapshot
- * persistence (trend display only; TASK_2341: never a revert/gate), and
- * Guardian periodic health check triggering.
- */
-
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-const { ROOT, COLLABORATION_API } = require('../utils');
-
-// Constants: natural home is this module (previously misplaced in cognitive.js)
-const GUARDIAN_COUNTER_FILE = path.join(__dirname, '..', '..', '.synapse', 'guardian_counter.json');
-const HEALTH_SNAPSHOTS_DIR_NAME = path.join('.kenaz', 'health_snapshots');
-const DEFAULT_REVERT_THRESHOLD = -2;
-// TASK_2341: tag for snapshots of the memory-only health score. Graph-era snapshots have no
-// score_version, so they are never compared with these (see computeHealthVerdict).
-const MEMORY_SCORE_VERSION = 'memory-v1';
-
-// TASK_1726: Producer-side heartbeat observability.
-const CHANNEL_HB_RELPATH = require('path').join('.kenaz', 'channel_heartbeats.jsonl');
-const CHANNEL_HB_CAP = 5000; // lines; rotate to .bak when exceeded
-
-/**
- * Append one heartbeat line to .kenaz/channel_heartbeats.jsonl.
- * Bounded: rotates to .bak when CHANNEL_HB_CAP lines exceeded.
- * Never throws -- heartbeat must never break the calling path.
- * @param {string} root   project root
- * @param {string} channel  logical channel name
- * @param {boolean} ok    true=write succeeded, false=write failed
- * @param {string} [note]  optional context
- */
-function appendChannelHeartbeat(root, channel, ok, note) {
-  try {
-    const hbPath = require('path').join(root, CHANNEL_HB_RELPATH);
-    const dir = require('path').dirname(hbPath);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    if (fs.existsSync(hbPath)) {
-      const count = fs.readFileSync(hbPath, 'utf8').split('\n').filter(l => l.trim()).length;
-      if (count >= CHANNEL_HB_CAP) fs.renameSync(hbPath, hbPath + '.bak');
-    }
-    const line = JSON.stringify({ channel, ts: new Date().toISOString(), ok, ...(note ? { note } : {}) });
-    fs.appendFileSync(hbPath, line + '\n', 'utf8');
-  } catch { /* never throw */ }
-}
-
-/**
- * TASK_2038: resolve the projectPath every MCP/HTTP payload sent by the
- * post-complete module family must carry EXPLICITLY. Local, file-based reads
- * in this same file already do `projectPath || ROOT` (e.g.
- * readPreTaskHealthSnapshot, saveTaskHealthSnapshot) -- but every MCP/HTTP
- * payload instead spread `...(projectPath ? { projectPath } : {})`, which
- * OMITS the key entirely for a core KenazAI run (projectPath is undefined
- * there -- see post-complete.js ~L4016, only set when --project-path is
- * passed). synapse_health and friends then fall back server-side to whatever
- * project the Dashboard currently has selected, not this run's actual
- * project -- confirmed live: 4 of 5 recent KEEP/REVERT verdicts were scored
- * against a different repo (rune_ec9ec6c1). One helper instead of repeating
- * `|| ROOT` at each MCP call site (GEN-008: ROOT is post-complete's existing
- * dynamically-resolved constant, not a hardcoded path).
- * @param {string} [projectPath]
- * @returns {string}
- */
-function resolveMcpProjectPath(projectPath) {
-  return projectPath || ROOT;
-}
-
-/**
- * TASK_1861 introduced the KENAZ_DASHBOARD_PORT env override so tests can
- * point measureHealthScoreSync at a stub server instead of the real
- * Dashboard. TASK_2038 needs the identical override in
- * triggerGuardianHealthCheck (which used to hardcode port 18080) so its own
- * negative-control test can run against the same stub -- one resolver
- * instead of two copies of the parse/validate logic drifting apart.
- * @returns {number}
- */
-function resolveMcpDashboardPort() {
-  const envPort = parseInt(process.env.KENAZ_DASHBOARD_PORT || '', 10);
-  return Number.isInteger(envPort) && envPort > 0 && envPort <= 65535 ? envPort : 18080;
-}
-
-/**
- * Read loop configuration from .kenaz/loop/loop.json.
- * Determines if KEEP/REVERT logic runs (auto mode only).
- *
- * TASK_1885: the file is written exclusively by loop_config.rs, whose
- * LoopConfig struct carries #[serde(rename_all = "camelCase")] -- so the
- * on-disk key is `revertThreshold`, not `revert_threshold`. There has never
- * been a snake_case writer (loop.js's own readLoopConfig/default and the
- * Rust struct both agree on camelCase), so this reads the single real key
- * with no dual-format acceptance window -- a snake_case branch here would
- * be dead code with no producer. The returned object keeps `revert_threshold`
- * as the JS-internal field name; that shape is unrelated to the on-disk key
- * and is what every consumer in this codebase already destructures.
- * @param {string} [projectPath]
- * @returns {{ mode: string, revert_threshold: number }}
- */
-function readLoopConfig(projectPath) {
-  const root = projectPath || ROOT;
-  const loopFile = path.join(root, '.kenaz', 'loop', 'loop.json');
-  try {
-    if (fs.existsSync(loopFile)) {
-      const data = JSON.parse(fs.readFileSync(loopFile, 'utf8'));
-      return {
-        mode: data.mode || 'manual',
-        revert_threshold: typeof data.revertThreshold === 'number'
-          ? data.revertThreshold
-          : DEFAULT_REVERT_THRESHOLD,
-      };
-    }
-  } catch { /* corrupted ??use defaults */ }
-  return { mode: 'manual', revert_threshold: DEFAULT_REVERT_THRESHOLD };
-}
-
-/**
- * Synchronously measure Synapse health score via MCP HTTP endpoint.
- * Spawns a Node.js subprocess to work around Node's async-only HTTP.
- *
- * TASK_1893: the inline script also preserves the raw `metrics` object
- * verbatim as `metrics_raw`, alongside (not replacing) the existing flat
- * `sub_metrics: {name: number}` projection. This is the general fix for
- * a producer/consumer disconnect that had already recurred twice on this
- * exact line: TASK_1890 patched metric_trust + saturated_default through
- * by name; three weeks and one field later (pain_path_count.metric_version,
- * TASK_1889) the same projection dropped the new field again, because
- * naming fields one at a time doesn't generalize. metrics_raw closes the
- * hole for good -- any future per-metric field health.rs adds is preserved
- * automatically, with no fourth card required. sub_metrics/
- * sub_metrics_saturated are NOT widened to carry it, because their flat
- * `{name: number}` / `{name: boolean}` shape is a load-bearing contract
- * consumed in four places by `typeof === 'number'`/truthiness
- * (computeSubMetricDeltas, pairedSubMetricDeltas, deriveSideTrust, and the
- * 191 on-disk _after.json snapshots) -- widening it would break all of
- * them silently.
- * @param {string} [projectPath]
- * @returns {{ score: number, grade: string, sub_metrics?: object, sub_metrics_saturated?: object, metric_trust?: object|null, metrics_raw?: object } | null} null if dashboard not running
- */
-function measureHealthScoreSync(projectPath) {
-  // TASK_2038: resolve BEFORE building the inline script so `pp` is always a
-  // real path (never omitted) -- see resolveMcpProjectPath's JSDoc.
-  const ppArg = JSON.stringify(resolveMcpProjectPath(projectPath));
-  // TASK_1861: KENAZ_DASHBOARD_PORT env override (test injection / non-default port).
-  // Invalid or absent values fall back to the production default 18080.
-  const port = resolveMcpDashboardPort();
-  // Inline node script: makes async HTTP request, writes JSON result to stdout
-  const script = [
-    "const http = require('http');",
-    `const pp = ${ppArg};`,
-    "const payload = JSON.stringify({ jsonrpc: '2.0', id: 'hc-sync', method: 'tools/call',",
-    "  params: { name: 'synapse_health',",
-    "    arguments: { mode: 'score', save_snapshot: true, projectPath: pp } } });",
-    `const req = http.request({ hostname: '127.0.0.1', port: ${port}, path: '/api/mcp',`,
-    "  method: 'POST',",
-    "  headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },",
-    "  timeout: 8000 }, (res) => {",
-    "  let b = '';",
-    "  res.on('data', c => b += c);",
-    "  res.on('end', () => {",
-    "    try {",
-    "      const r = JSON.parse(b);",
-    "      const t = r && r.result && r.result.content && r.result.content[0] && r.result.content[0].text;",
-    "      if (t) { const d = JSON.parse(t);",
-    "        const sm = d.metrics ? Object.fromEntries(Object.entries(d.metrics).map(([k,v]) => [k, typeof v === 'object' ? v.score : v])) : {};",
-    "        const smSat = d.metrics ? Object.fromEntries(Object.entries(d.metrics).map(([k,v]) => [k, !!(v && typeof v === 'object' && v.saturated_default)])) : {};",
-    "        const mt = (d.metric_trust && typeof d.metric_trust === 'object') ? d.metric_trust : null;",
-    // TASK_1893: preserve the whole metrics object verbatim, alongside (not
-    // instead of) the flat sm/smSat projections above -- see the JSDoc on
-    // measureHealthScoreSync for why this is the general fix rather than
-    // naming another field.
-    "        const metricsRaw = (d.metrics && typeof d.metrics === 'object') ? d.metrics : {};",
-    "        process.stdout.write(JSON.stringify({ score: d.overall_score, grade: d.grade, sub_metrics: sm, sub_metrics_saturated: smSat, metric_trust: mt, metrics_raw: metricsRaw }));",
-    "      }",
-    "    } catch(e) { process.stderr.write(e.message); }",
-    "  });",
-    "});",
-    "req.on('error', () => {});",
-    "req.on('timeout', () => req.destroy());",
-    "req.write(payload);",
-    "req.end();",
-  ].join('\n');
-
-  try {
-    const result = spawnSync(process.execPath, ['-e', script], {
-      encoding: 'utf8',
-      timeout: 12000,
-      windowsHide: true,
-    });
-    if (result.stdout && result.stdout.trim()) {
-      // TASK_2341: tag so memory-era scores are never compared with graph-era ones.
-      return { ...JSON.parse(result.stdout.trim()), score_version: MEMORY_SCORE_VERSION };
-    }
-  } catch { /* dashboard not running or timeout */ }
-  return null;
-}
-
-/**
- * Read pre-task health snapshot from disk.
- * Written by headless.js at dispatch time, keyed by task_id.
- * @param {string} taskId
- * @param {string} [projectPath]
- * @returns {{ score: number, grade: string, timestamp: string } | null}
- */
-function readPreTaskHealthSnapshot(taskId, projectPath) {
-  const root = projectPath || ROOT;
-  const snapshotFile = path.join(root, HEALTH_SNAPSHOTS_DIR_NAME, `${taskId}_before.json`);
-  try {
-    if (fs.existsSync(snapshotFile)) {
-      return JSON.parse(fs.readFileSync(snapshotFile, 'utf8'));
-    }
-  } catch {}
-  return null;
-}
-
-/**
- * Save a health snapshot for a task (before or after).
- * Includes sub_metrics if present in health object (TASK_1455).
- * TASK_1890: also persists metric_trust (overall_trust, submetric_trust,
- * risk_flags, sampling_info, index_staleness_hours) and per-metric
- * saturated_default flags -- without this, a snapshot read back later (e.g.
- * as a stand-in "before" reading, or for post-hoc audit) can never recover
- * how trustworthy the graph was at measurement time, and any consumer is
- * forced back onto the optimistic default this task exists to eliminate.
- * TASK_1893: also persists metrics_raw (the unprojected metrics object,
- * including per-metric fields like pain_path_count.metric_version) --
- * without this a snapshot can never recover which FORMULA a metric was
- * computed under, only its score, so a before/after pair spanning a formula
- * change reads as an ordinary delta instead of an incomparable one.
- * @param {string} taskId
- * @param {'before'|'after'} type
- * @param {{ score: number, grade: string, sub_metrics?: object, sub_metrics_saturated?: object, metric_trust?: object|null, metrics_raw?: object }} health
- * @param {string} [projectPath]
- * @returns {object|null} the exact payload written to disk (score, grade,
- *   sub_metrics, sub_metrics_saturated, metric_trust, metrics_raw, timestamp,
- *   and on 'after' also delta_from_previous/trend_5tasks), or null on write
- *   failure.
- *   TASK_1891: returning this lets callers thread delta_from_previous through
- *   to computeHealthVerdict for observability -- previously computed here and
- *   then silently discarded (rune_9d645791: "no verdict path reads it").
- */
-function saveTaskHealthSnapshot(taskId, type, health, projectPath) {
-  const root = projectPath || ROOT;
-  const dir = path.join(root, HEALTH_SNAPSHOTS_DIR_NAME);
-  let writeOk = false;
-  let writeNote;
-  let writtenPayload = null;
-  try {
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    const payload = {
-      score: health.score,
-      grade: health.grade,
-      score_version: health.score_version || MEMORY_SCORE_VERSION,
-      sub_metrics: health.sub_metrics || {},
-      sub_metrics_saturated: health.sub_metrics_saturated || {},
-      metric_trust: health.metric_trust || null,
-      metrics_raw: health.metrics_raw || {},
-      timestamp: new Date().toISOString(),
-    };
-    // Enrich _after snapshots with delta_from_previous and trend_5tasks (TASK_1431)
-    // Priors are loaded BEFORE writing current file, so current task is naturally excluded.
-    if (type === 'after') {
-      try {
-        const priors = loadRecentAfterSnapshots(root, 5);
-        payload.delta_from_previous = priors.length >= 1 && typeof priors[0].score === 'number'
-          ? parseFloat((health.score - priors[0].score).toFixed(2))
-          : null;
-        payload.trend_5tasks = priors.length >= 5 && typeof priors[4].score === 'number'
-          ? parseFloat((health.score - priors[4].score).toFixed(2))
-          : null;
-      } catch { payload.delta_from_previous = null; payload.trend_5tasks = null; }
-    }
-    fs.writeFileSync(
-      path.join(dir, `${taskId}_${type}.json`),
-      JSON.stringify(payload, null, 2)
-    );
-    writeOk = true;
-    writtenPayload = payload;
-  } catch (e) {
-    // TASK_1726: warn-on-silent-skip
-    console.warn(`[channel:health_snapshot] write failed for ${taskId}_${type}: ${e && e.message || e}`);
-    writeNote = String(e && e.message || e);
-  }
-  // TASK_1726: heartbeat on every call (ok or not)
-  appendChannelHeartbeat(root, 'health_snapshot', writeOk, writeNote);
-  return writtenPayload;
-}
-
-/**
- * Load the N most recent _after.json snapshots (TASK_1455).
- * Used for sub-metric trend analysis in SUBMETRIC_REGRESSION verdict.
- * @param {string} [projectPath]
- * @param {number} [limit=10]
- * @returns {Array<{ taskId: string, score: number, grade: string, sub_metrics: object, timestamp: string }>}
- */
-function loadRecentAfterSnapshots(projectPath, limit = 10) {
-  const root = projectPath || ROOT;
-  const dir = path.join(root, HEALTH_SNAPSHOTS_DIR_NAME);
-  if (!fs.existsSync(dir)) return [];
-  try {
-    // Sort by recorded content timestamp (deterministic), falling back to file mtime
-    // only when the timestamp is missing/unparseable. mtime alone ties when many
-    // snapshots are written in the same millisecond, producing unstable ordering.
-    return fs.readdirSync(dir)
-      .filter(f => f.endsWith('_after.json'))
-      .map(f => {
-        try {
-          const data = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
-          const ts = Date.parse(data.timestamp);
-          return {
-            taskId: f.replace('_after.json', ''),
-            score_version: data.score_version || null,
-            score: data.score ?? null,
-            grade: data.grade ?? null,
-            sub_metrics: data.sub_metrics || {},
-            timestamp: data.timestamp || null,
-            _sortKey: Number.isNaN(ts) ? fs.statSync(path.join(dir, f)).mtimeMs : ts,
-          };
-        } catch { return null; }
-      })
-      .filter(Boolean)
-      // TASK_2341: only same-version (memory-v1) snapshots form a comparable trend.
-      .filter(x => x.score_version === MEMORY_SCORE_VERSION)
-      .sort((a, b) => b._sortKey - a._sortKey) // newest first by recorded timestamp
-      .slice(0, limit)
-      .map(({ _sortKey, ...rest }) => rest);
-  } catch { return []; }
-}
-
-/**
- * TASK_2341: memory-health trend record. NEVER a gate.
- *
- * synapse_health now scores MEMORY (rune_vitality, review_backlog, conflict_load,
- * episode_backlog), not code. A code change cannot move that score, so no verdict
- * derived from it may revert, block or penalise a task. This function therefore
- * always returns verdict 'RECORDED'; `delta` is informational and is only a number
- * when the before snapshot carries the same score_version (graph-era snapshots have
- * none and are never compared with memory-era ones).
- * @param {object|number} preSnapshotOrScore
- * @param {{score:number, score_version?:string}} postHealth
- * @param {number} [_threshold] ignored (kept for caller compatibility)
- * @param {{trendDeltaFromPrevious?: number|null}} [opts]
- * @returns {{delta: number|null, score: number, verdict: 'RECORDED', reason: string,
- *   subMetricRegressions: string[], trust: object, indeterminateReason: null,
- *   trendDeltaFromPrevious: number|null}}
- */
-function computeHealthVerdict(preSnapshotOrScore, postHealth, _threshold, opts = {}) {
-  const preSn = typeof preSnapshotOrScore === 'number' ? { score: preSnapshotOrScore } : (preSnapshotOrScore || {});
-  const score = postHealth.score;
-  const version = postHealth.score_version || MEMORY_SCORE_VERSION;
-  const comparable = typeof preSn.score === 'number' && preSn.score_version === version;
-  const delta = comparable ? score - preSn.score : null;
-  const reason = comparable
-    ? `Memory-health trend ${delta >= 0 ? '+' : ''}${Number(delta).toFixed(1)} pts (${version}) — recorded for display only, never gates`
-    : `Memory-health ${score}/100 (${version}) recorded; baseline is ${preSn.score_version || 'graph-era'} so not compared`;
-  return {
-    delta, score, verdict: 'RECORDED', reason, subMetricRegressions: [],
-    trust: { status: 'unknown', overall_trust: null, risk_flags: [] },
-    indeterminateReason: null,
-    trendDeltaFromPrevious: opts.trendDeltaFromPrevious ?? null,
-  };
-}
-
-
-/**
- * Write the RECORDED health note to task YAML via task-api notes field.
- * Field format: "post_complete_verdict: RECORDED | delta: N|n/a | reason: ..."
- * @param {string} taskId
- * @param {string} verdict
- * @param {number|null} delta
- * @param {string} reason
- * @param {string} [projectPath]
- */
-function writeVerdictToTask(taskId, verdict, delta, reason, projectPath) {
-  try {
-    const deltaText = typeof delta === 'number' ? delta.toFixed(2) : 'n/a';
-    const updateArgs = projectPath ? ['--project-path', projectPath] : [];
-    const verdictNote = `post_complete_verdict: ${verdict} | delta: ${deltaText} | reason: ${reason}`;
-    updateArgs.push('update', taskId, '--notes', verdictNote);
-    spawnSync('node', [COLLABORATION_API, ...updateArgs], {
-      encoding: 'utf8', timeout: 10000, cwd: ROOT, windowsHide: true,
-    });
-  } catch { /* best-effort */ }
-}
-
-function readGuardianCounter() {
-  try {
-    if (fs.existsSync(GUARDIAN_COUNTER_FILE)) {
-      return JSON.parse(fs.readFileSync(GUARDIAN_COUNTER_FILE, 'utf8'));
-    }
-  } catch { /* corrupted ??reset */ }
-  return { completed_since_last_health: 0 };
-}
-
-function writeGuardianCounter(data) {
-  try {
-    const dir = path.dirname(GUARDIAN_COUNTER_FILE);
-    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(GUARDIAN_COUNTER_FILE, JSON.stringify(data, null, 2));
-  } catch { /* best-effort */ }
-}
-
-/**
- * Fire-and-forget: call synapse_health via MCP HTTP endpoint.
- * Saves a snapshot for trend tracking. Non-blocking, non-failing.
- */
-function triggerGuardianHealthCheck(projectPath) {
-  const http = require('http');
-  // TASK_2038: explicit projectPath (never omitted) + same KENAZ_DASHBOARD_PORT
-  // override as measureHealthScoreSync -- see resolveMcpProjectPath/
-  // resolveMcpDashboardPort JSDoc.
-  const payload = JSON.stringify({
-    jsonrpc: '2.0', id: `guardian-${Date.now()}`, method: 'tools/call',
-    params: {
-      name: 'synapse_health',
-      arguments: { mode: 'score', save_snapshot: true, projectPath: resolveMcpProjectPath(projectPath) }
-    }
-  });
-  const req = http.request({
-    hostname: '127.0.0.1', port: resolveMcpDashboardPort(), path: '/api/mcp',
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
-    timeout: 10000
-  }, (res) => {
-    let body = '';
-    res.on('data', (chunk) => { body += chunk; });
-    res.on('end', () => {
-      try {
-        const result = JSON.parse(body);
-        const content = result?.result?.content?.[0]?.text;
-        if (content) {
-          const data = JSON.parse(content);
-          console.log(`   ?儭? Guardian: health=${data.overall_score}/100 (${data.grade}) ??snapshot saved`);
-        }
-      } catch { console.log('   ?儭? Guardian: health snapshot saved'); }
-    });
-  });
-  req.on('error', () => { /* Dashboard not running ??skip silently */ });
-  req.on('timeout', () => { req.destroy(); });
-  req.write(payload);
-  req.end();
-}
-
-module.exports = {
-  resolveMcpProjectPath,
-  resolveMcpDashboardPort,
-  readLoopConfig,
-  measureHealthScoreSync,
-  readPreTaskHealthSnapshot,
-  saveTaskHealthSnapshot,
-  loadRecentAfterSnapshots,
-  computeHealthVerdict,
-  writeVerdictToTask,
-  readGuardianCounter,
-  writeGuardianCounter,
-  triggerGuardianHealthCheck,
-  appendChannelHeartbeat,
-  GUARDIAN_COUNTER_FILE,
-  HEALTH_SNAPSHOTS_DIR_NAME,
-  DEFAULT_REVERT_THRESHOLD,
-  MEMORY_SCORE_VERSION,
-  CHANNEL_HB_RELPATH,
-};