@mindrian_os/install 1.13.0-beta.13 → 1.13.0-beta.16

package/lib/core/feynman/timeline-renderer.cjs

@@ -0,0 +1,197 @@
+'use strict';
+// Phase 124-01 -- FEYNMAN.md timeline renderer
+// ===========================================
+// Pure function. Given (db, sectionSlug, opts) returns { markdown_body, summary_stats }.
+// Reads ONLY via lib/core/navigation.cjs (the Phase 109 closed chokepoint per D-03).
+// ZERO filesystem reads. ZERO Brain calls. ZERO LLM calls.
+//
+// Canon Part 9: the Larry-explains face of memory_event -- structured SQL becomes
+// human-readable explanation strings via templated rendering, never LLM in the loop.
+//
+// Canon Part 8: zero net new Brain surface; the renderer is local-only.
+//
+// Canon Part 5: "stale" is a context signal (4 buckets: recent / quiet / stale / dormant)
+// alongside the existing evidence tier; thresholds frozen at 7 / 30 / 90 days per D-06.
+//
+// Output format (D-05 LOCKED):
+//   *Last refreshed: {ISO}. {N} insight events, first captured {first_iso}, last touched {last_iso} ({last_delta_human}).*
+//
+//   **Recent events** (within 7 days, top 5):
+//   - {iso}: {event_type} -- {one_line_explain}
+//   - ...
+//
+//   **Flagged stale** (over 30 days untouched, top 5):
+//   - {iso}: {event_type} on {target_summary} -- last touched {delta_human}
+//   - ...
+//
+//   **Health:** recent={n_recent} / quiet={n_quiet} / stale={n_stale} / dormant={n_dormant}.
+//
+// Empty state (zero memory_event rows scoped to section):
+//   *No timeline events yet.*
+
+const navigation = require('../navigation.cjs');
+
+// ---------- D-06 thresholds ----------
+
+const THRESHOLDS = Object.freeze({
+  recent_ms: 7 * 24 * 60 * 60 * 1000,
+  quiet_ms: 30 * 24 * 60 * 60 * 1000,
+  stale_ms: 90 * 24 * 60 * 60 * 1000,
+});
+
+function resolveThresholds() {
+  const raw = process.env.MINDRIAN_TIMELINE_THRESHOLDS_JSON;
+  if (!raw) return THRESHOLDS;
+  try {
+    const parsed = JSON.parse(raw);
+    const r = Number.isFinite(parsed.recent_ms) ? parsed.recent_ms : THRESHOLDS.recent_ms;
+    const q = Number.isFinite(parsed.quiet_ms) ? parsed.quiet_ms : THRESHOLDS.quiet_ms;
+    const s = Number.isFinite(parsed.stale_ms) ? parsed.stale_ms : THRESHOLDS.stale_ms;
+    if (!(r < q && q < s)) return THRESHOLDS;
+    return Object.freeze({ recent_ms: r, quiet_ms: q, stale_ms: s });
+  } catch (_) {
+    return THRESHOLDS;
+  }
+}
+
+// ---------- ISO + human delta helpers ----------
+
+function isoSecond(ms) {
+  if (!Number.isFinite(ms)) return '';
+  return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function humanDelta(deltaMs) {
+  if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'unknown';
+  const sec = Math.floor(deltaMs / 1000);
+  if (sec < 60) return sec + ' seconds ago';
+  const min = Math.floor(sec / 60);
+  if (min < 60) return min + ' minutes ago';
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return hr + ' hours ago';
+  const days = Math.floor(hr / 24);
+  if (days < 30) return days + ' days ago';
+  const months = Math.floor(days / 30);
+  if (months < 12) return months + ' months ago';
+  const years = Math.floor(days / 365);
+  return years + ' years ago';
+}
+
+// ---------- Section scoping (D-08) ----------
+
+function isInSection(sourcePath, sectionSlug) {
+  if (typeof sourcePath !== 'string' || typeof sectionSlug !== 'string') return false;
+  if (sourcePath === sectionSlug) return true;
+  return sourcePath.startsWith(sectionSlug + '/');
+}
+
+// ---------- Explanation strings (templated; colocated fallback) ----------
+//
+// The Phase 109-05 renderExplanation(kind, payload) signature does not directly
+// match the memory_event row shape returned by findRecentChanges, so we use a
+// colocated templated fallback that renders generic event_type + target_node_id.
+// Zero LLM in the loop -- the strings are pure string concatenation over typed
+// SQL fields.
+
+function oneLineExplain(row) {
+  // row = { eventType, targetNodeId, sourcePath, properties, createdAt }
+  const tgt = row && row.targetNodeId ? (' on ' + row.targetNodeId) : '';
+  const evt = (row && row.eventType) ? row.eventType : 'event';
+  return evt + tgt;
+}
+
+// ---------- The renderer ----------
+
+function renderTimeline(db, sectionSlug, opts) {
+  const options = opts || {};
+  const now_ms = Number.isFinite(options.now_ms) ? options.now_ms : Date.now();
+  const thresholds = resolveThresholds();
+
+  // 1. Summary stats (first / last / total) via the new navigation primitive (D-08 scoping).
+  const summary = navigation.firstCapturedLastTouchedBySection(db, sectionSlug);
+
+  // Empty-state branch (D-05): zero memory_event rows scoped to the section.
+  if (summary.total_events === 0) {
+    return {
+      markdown_body: '*No timeline events yet.*',
+      summary_stats: { total_events: 0, n_recent: 0, n_quiet: 0, n_stale: 0, n_dormant: 0 },
+    };
+  }
+
+  // 2. Recent events (within recent_ms; section-scoped post-fetch filter).
+  // findRecentChanges returns rows for the WHOLE room; we filter by sourcePath per D-08.
+  const recentLookback = thresholds.recent_ms;
+  let allRecent = [];
+  try {
+    allRecent = navigation.findRecentChanges(db, now_ms - recentLookback, { limit: 200 }) || [];
+  } catch (_) { allRecent = []; }
+  const scopedRecent = allRecent.filter((r) => isInSection(r.sourcePath, sectionSlug));
+  const topRecent = scopedRecent.slice(0, 5);
+
+  // 3. Flagged stale: rows whose delta sits in the [quiet_ms .. stale_ms) window.
+  let allStaleWindow = [];
+  try {
+    const sinceStale = now_ms - thresholds.stale_ms;
+    const allWindow = navigation.findRecentChanges(db, sinceStale, { limit: 500 }) || [];
+    allStaleWindow = allWindow.filter((r) => isInSection(r.sourcePath, sectionSlug)
+      && Number.isFinite(r.createdAt)
+      && (now_ms - r.createdAt) >= thresholds.quiet_ms
+      && (now_ms - r.createdAt) < thresholds.stale_ms);
+  } catch (_) { allStaleWindow = []; }
+  const topStale = allStaleWindow.slice(0, 5);
+
+  // 4. Health buckets across ALL memory_event rows scoped to the section.
+  let allRows = [];
+  try {
+    allRows = navigation.findRecentChanges(db, 0, { limit: 10000 }) || [];
+  } catch (_) { allRows = []; }
+  const scoped = allRows.filter((r) => isInSection(r.sourcePath, sectionSlug)
+    && Number.isFinite(r.createdAt));
+  let n_recent = 0, n_quiet = 0, n_stale = 0, n_dormant = 0;
+  for (const r of scoped) {
+    const delta = now_ms - r.createdAt;
+    if (delta < thresholds.recent_ms) n_recent += 1;
+    else if (delta < thresholds.quiet_ms) n_quiet += 1;
+    else if (delta < thresholds.stale_ms) n_stale += 1;
+    else n_dormant += 1;
+  }
+
+  // 5. Assemble the D-05 markdown body.
+  const lines = [];
+  const firstIso = isoSecond(summary.first_captured_ms);
+  const lastIso = isoSecond(summary.last_touched_ms);
+  const lastDeltaHuman = humanDelta(now_ms - summary.last_touched_ms);
+  const nowIso = isoSecond(now_ms);
+  lines.push('*Last refreshed: ' + nowIso + '. ' + summary.total_events + ' insight events, first captured '
+    + firstIso + ', last touched ' + lastIso + ' (' + lastDeltaHuman + ').*');
+  lines.push('');
+  lines.push('**Recent events** (within 7 days, top 5):');
+  if (topRecent.length === 0) {
+    lines.push('- (none in the last 7 days)');
+  } else {
+    for (const r of topRecent) {
+      lines.push('- ' + isoSecond(r.createdAt) + ': ' + (r.eventType || 'event') + ' -- ' + oneLineExplain(r));
+    }
+  }
+  lines.push('');
+  lines.push('**Flagged stale** (over 30 days untouched, top 5):');
+  if (topStale.length === 0) {
+    lines.push('- (none over 30 days untouched)');
+  } else {
+    for (const r of topStale) {
+      const tgt = r.targetNodeId || '(unscoped)';
+      lines.push('- ' + isoSecond(r.createdAt) + ': ' + (r.eventType || 'event') + ' on ' + tgt
+        + ' -- last touched ' + humanDelta(now_ms - r.createdAt));
+    }
+  }
+  lines.push('');
+  lines.push('**Health:** recent=' + n_recent + ' / quiet=' + n_quiet + ' / stale=' + n_stale
+    + ' / dormant=' + n_dormant + '.');
+
+  return {
+    markdown_body: lines.join('\n'),
+    summary_stats: { total_events: summary.total_events, n_recent, n_quiet, n_stale, n_dormant },
+  };
+}
+
+module.exports = { renderTimeline, THRESHOLDS, resolveThresholds, isoSecond, humanDelta, isInSection };

package/lib/core/feynman/timeline-runner.cjs

@@ -0,0 +1,281 @@
+'use strict';
+// Phase 124-02 -- FEYNMAN.md timeline runner
+// =========================================
+// The side-effect orchestrator. Walks a room's section folders, finds each FEYNMAN.md,
+// applies the D-02 sentinel-bounded merge over the body returned by the pure renderer
+// (Plan 124-01), writes back atomically (.tmp + rename), updates the timeline_last_rendered
+// frontmatter, and logs a memory_event on every refresh attempt (success or failure).
+//
+// Honors the D-09 watermark contract: skip when the frontmatter timeline_last_rendered ISO
+// is >= the SQL MAX(memory_event.created_at) ISO for the section (second-resolution).
+//
+// The renderer (timeline-renderer.cjs) is the pure function. The runner is the impure shell
+// around it. tests/test-feynman-timeline-runner.cjs is the integration test for this module.
+//
+// Canon Part 9: every refresh logs a typed memory_event making the regenerate-vs-skip
+// decision legible in the local mind. Canon Part 8: zero net new Brain surface.
+// Canon Part 7: reuses the atomic .tmp + rename idiom from scripts/vault-section-minto-generator.cjs;
+//               the frontmatter line-walk parser idiom from scripts/frontmatter-schema-validator.cjs.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const renderer = require('./timeline-renderer.cjs');
+const navigation = require('../navigation.cjs');
+
+// ---------- Sentinel contract (D-02) ----------
+
+const SENTINEL_START = '<!-- TIMELINE_AUTO_START -->';
+const SENTINEL_END = '<!-- TIMELINE_AUTO_END -->';
+const HEADER = '## Timeline (auto)';
+
+// ---------- Frontmatter helpers (hand-rolled; no gray-matter) ----------
+
+function parseFrontmatter(content) {
+  // Returns { fm: { [key]: value }, fmOrder: [keys...], body: '<rest>', hadFrontmatter: bool }.
+  const lines = content.split('\n');
+  if (lines.length === 0 || lines[0].trim() !== '---') {
+    return { fm: {}, fmOrder: [], body: content, hadFrontmatter: false };
+  }
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { endIdx = i; break; }
+  }
+  if (endIdx === -1) {
+    return { fm: {}, fmOrder: [], body: content, hadFrontmatter: false };
+  }
+  const fmLines = lines.slice(1, endIdx);
+  const bodyLines = lines.slice(endIdx + 1);
+  const fm = {};
+  const fmOrder = [];
+  for (const ln of fmLines) {
+    const m = ln.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    const raw = m[2];
+    let val;
+    if (raw === '' || raw === 'null') val = null;
+    else if (raw === 'true') val = true;
+    else if (raw === 'false') val = false;
+    else if (/^-?\d+(\.\d+)?$/.test(raw)) val = Number(raw);
+    else if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) val = raw.slice(1, -1);
+    else val = raw;
+    fm[key] = val;
+    if (fmOrder.indexOf(key) === -1) fmOrder.push(key);
+  }
+  return { fm: fm, fmOrder: fmOrder, body: bodyLines.join('\n'), hadFrontmatter: true };
+}
+
+function serializeFrontmatter(fm, fmOrder, body, hadFrontmatter) {
+  // If fm is empty AND there was no original frontmatter -> return body unchanged.
+  const keys = Object.keys(fm);
+  if (keys.length === 0 && !hadFrontmatter) return body;
+  // Honor fmOrder for existing keys; append any new keys not in fmOrder at the end.
+  const order = fmOrder.slice();
+  for (const k of keys) {
+    if (order.indexOf(k) === -1) order.push(k);
+  }
+  const out = ['---'];
+  for (const k of order) {
+    if (!(k in fm)) continue;
+    const v = fm[k];
+    if (v === null) out.push(k + ':');
+    else if (typeof v === 'boolean' || typeof v === 'number') out.push(k + ': ' + String(v));
+    else out.push(k + ': ' + String(v));
+  }
+  out.push('---');
+  return out.join('\n') + '\n' + body;
+}
+
+// ---------- Sentinel-bounded merge (D-02 hard invariant) ----------
+
+function mergeSentinelSection(body, renderedBody) {
+  // Case A: the sentinel pair exists -- replace the content between.
+  const startIdx = body.indexOf(SENTINEL_START);
+  const endIdx = body.indexOf(SENTINEL_END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const before = body.slice(0, startIdx + SENTINEL_START.length);
+    const after = body.slice(endIdx);
+    return before + '\n' + renderedBody + '\n' + after;
+  }
+  // Case B: no sentinel pair -- append at end-of-file (ensure trailing newline).
+  const sep = body.endsWith('\n') ? '' : '\n';
+  return body + sep + '\n' + HEADER + '\n\n' + SENTINEL_START + '\n' + renderedBody + '\n' + SENTINEL_END + '\n';
+}
+
+function bodyOutsideSentinels(body) {
+  // For the SHA256 byte-preservation check. Returns the body with the sentinel block excised
+  // (everything from SENTINEL_START to SENTINEL_END inclusive removed, plus the lines they
+  // sit on). If no sentinels, returns the body unchanged.
+  const startIdx = body.indexOf(SENTINEL_START);
+  const endIdx = body.indexOf(SENTINEL_END);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return body;
+  // Find the start of the line containing SENTINEL_START (back up to the previous newline)
+  // and the end of the line containing SENTINEL_END (forward to the next newline).
+  let lineStart = body.lastIndexOf('\n', startIdx);
+  if (lineStart === -1) lineStart = 0;
+  let lineEnd = body.indexOf('\n', endIdx + SENTINEL_END.length);
+  if (lineEnd === -1) lineEnd = body.length;
+  return body.slice(0, lineStart) + body.slice(lineEnd);
+}
+
+function sha256Hex(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// ---------- Atomic write (D-02 hard invariant: no partial-write corruption) ----------
+
+function atomicWrite(targetPath, content) {
+  const dir = path.dirname(targetPath);
+  const base = path.basename(targetPath);
+  const tmp = path.join(dir, '.' + base + '.tmp.' + process.pid + '.' + Date.now());
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, content, 0, 'utf8');
+    try { fs.fsyncSync(fd); } catch (_) { /* fsync best-effort on platforms without it */ }
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, targetPath);
+}
+
+// ---------- Section walk ----------
+
+function safeIsDir(p) { try { return fs.statSync(p).isDirectory(); } catch (_) { return false; } }
+function safeIsFile(p) { try { return fs.statSync(p).isFile(); } catch (_) { return false; } }
+
+function findFeynmanSections(roomDir) {
+  // Subdirectories of roomDir that contain a FEYNMAN.md at <roomDir>/<section>/FEYNMAN.md.
+  if (!safeIsDir(roomDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(roomDir, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    if (ent.name.startsWith('.')) continue;
+    if (ent.name === 'node_modules') continue;
+    const feyPath = path.join(roomDir, ent.name, 'FEYNMAN.md');
+    if (safeIsFile(feyPath)) out.push({ slug: ent.name, feyPath: feyPath });
+  }
+  out.sort((a, b) => a.slug.localeCompare(b.slug));
+  return out;
+}
+
+// ---------- Watermark check (D-09) ----------
+
+function shouldSkipWatermark(db, sectionSlug, fmRendered) {
+  if (typeof fmRendered !== 'string' || fmRendered.length === 0) return false;
+  let summary;
+  try {
+    summary = navigation.firstCapturedLastTouchedBySection(db, sectionSlug);
+  } catch (_) {
+    return false;
+  }
+  if (!summary || summary.total_events === 0) return false; // no events; refresh to empty-state if needed.
+  const sqlIso = renderer.isoSecond(summary.last_touched_ms);
+  if (!sqlIso) return false;
+  // ISO 8601 second-resolution strings are lex-sortable.
+  return sqlIso <= fmRendered;
+}
+
+// ---------- The orchestrator ----------
+
+function refreshSection(roomDir, sectionSlug, opts) {
+  const options = opts || {};
+  const db = options.db;
+  const now_ms = Number.isFinite(options.now_ms) ? options.now_ms : Date.now();
+  const force = options.force === true;
+  const feyPath = path.join(roomDir, sectionSlug, 'FEYNMAN.md');
+
+  if (!safeIsFile(feyPath)) {
+    return { status: 'skipped_no_feynman', reason: 'no_feynman_md_in_section_dir' };
+  }
+
+  try {
+    const rawContent = fs.readFileSync(feyPath, 'utf8');
+    const parsed = parseFrontmatter(rawContent);
+
+    // D-09 watermark check.
+    if (!force && db && typeof parsed.fm.timeline_last_rendered === 'string') {
+      if (shouldSkipWatermark(db, sectionSlug, parsed.fm.timeline_last_rendered)) {
+        return { status: 'skipped_watermark', reason: 'sql_older_than_rendered' };
+      }
+    }
+
+    // Render (D-05). Reads ONLY via navigation.cjs.
+    const rendered = renderer.renderTimeline(db, sectionSlug, { now_ms: now_ms });
+
+    // Merge (D-02 hard invariant).
+    const newBody = mergeSentinelSection(parsed.body, rendered.markdown_body);
+
+    // Update frontmatter watermark (D-09).
+    const newIso = renderer.isoSecond(now_ms);
+    const newFm = Object.assign({}, parsed.fm, { timeline_last_rendered: newIso });
+    // Force frontmatter emission on every refresh (true so the watermark always lands at
+    // the top, even when the original file had no fences).
+    const newContent = serializeFrontmatter(newFm, parsed.fmOrder, newBody, true);
+
+    // Atomic write.
+    atomicWrite(feyPath, newContent);
+
+    // Log success memory_event (D-10).
+    if (db) {
+      try {
+        navigation.logMemoryEvent(db, 'feynman_timeline_refreshed', {
+          source_path: 'feynman:' + sectionSlug,
+          created_by: 'system',
+        });
+      } catch (_) { /* logging failure does not corrupt the refresh; the write already landed */ }
+    }
+
+    return { status: 'refreshed', written_path: feyPath, watermark: newIso };
+  } catch (err) {
+    const reason = (err && err.message) ? String(err.message).slice(0, 200) : 'unknown_error';
+    if (db) {
+      try {
+        navigation.logMemoryEvent(db, 'feynman_timeline_refresh_failed', {
+          source_path: 'feynman:' + sectionSlug,
+          created_by: 'system',
+          reason: reason,
+        });
+      } catch (_) { /* secondary failure is swallowed */ }
+    }
+    return { status: 'failed', reason: reason };
+  }
+}
+
+function refreshAll(roomDir, opts) {
+  const options = opts || {};
+  const refreshed = [];
+  const skipped = [];
+  const failed = [];
+  const sections = findFeynmanSections(roomDir);
+  for (const s of sections) {
+    const r = refreshSection(roomDir, s.slug, options);
+    if (r.status === 'refreshed') refreshed.push({ slug: s.slug, written_path: r.written_path, watermark: r.watermark });
+    else if (r.status === 'failed') failed.push({ slug: s.slug, reason: r.reason });
+    else skipped.push({ slug: s.slug, reason: r.reason || r.status });
+  }
+  return { refreshed: refreshed, skipped: skipped, failed: failed };
+}
+
+module.exports = {
+  refreshAll,
+  refreshSection,
+  parseFrontmatter,
+  serializeFrontmatter,
+  mergeSentinelSection,
+  bodyOutsideSentinels,
+  sha256Hex,
+  findFeynmanSections,
+  shouldSkipWatermark,
+  atomicWrite,
+  SENTINEL_START,
+  SENTINEL_END,
+  HEADER,
+};