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

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,
+};

package/lib/core/navigation/edges.cjs

@@ -0,0 +1,86 @@
+'use strict';
+// Phase 125-00 -- navigation.cjs edge-write primitive (per CONTEXT.md Pass 3 GAP-2
+// resolution). Adds writeEdge to the navigation.cjs closed surface as an additive
+// extension following the Phase 110-03 logMemoryEvent precedent.
+//
+// Canon Part 4: every choice is graph data; this is the chokepoint primitive that
+// lets Plan 06 selector-decisions.cjs + future Phases 116/117/118 write typed
+// cascade edges without bypassing the closed surface.
+//
+// Canon Part 7: reuse-before-build -- the UPSERT statement mirrors
+// lib/core/lazygraph-ops.cjs::upsertEdge (lines 990-1019) so sibling agents
+// emit edges via the same UPSERT shape and the navigation chokepoint stays
+// the single door for write traffic.
+//
+// Canon Part 8 invariant: writeEdge takes (db, params) -- a db handle owned by
+// the caller (via openRoomDb) -- so this module never opens room.db itself. Zero
+// direct room-db.cjs require here. The navigation pre-commit hook treats this
+// file as part of the navigation/* allow-list, NOT as a bypass.
+
+const crypto = require('node:crypto');
+
+// Closed edge-type allowlist enforced by writeEdge. Mirrors the EVENT_TYPES Set
+// pattern in lib/core/navigation/memory-events.cjs. Phase 125 ships DEFERRED +
+// REJECTED (D7 typed cascade edge surface for F.1 defer / F.2 reject). Future
+// phases (e.g. Phase 116 tension resolution, Phase 117 auto-explore, Phase 118
+// MVA) extend this Set additively without canon amendment -- same idiom as the
+// EVENT_TYPES additive blocks for Phases 88.2-00 / 89-07 / 116-00 / 117-00 /
+// 110-02.
+//
+// Tests assert a FLOOR (DEFERRED + REJECTED present) and Set-instance shape --
+// not an exact size -- so additive extensions cannot regress baseline.
+const ALLOWED_EDGE_TYPES = Object.freeze(new Set([
+  // Phase 125 D7 -- F-selector decision edges (LOCKED LOCAL per Canon Part 8).
+  'DEFERRED',
+  'REJECTED',
+]));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// writeEdge(db, params) -- the 15th-style additive re-export on the
+// navigation.cjs closed surface (see navigation.cjs header comment for the
+// canonical re-export pattern alongside logMemoryEvent + firstCapturedLastTouchedBySection).
+//
+// Positional db (first arg, owned by caller via openRoomDb), params object
+// (second arg) with: { source_id, target_id, edge_type, properties }.
+//
+// Returns { ok: true, edge_id, type, source, target } on success, or
+// { ok: false, reason, detail? } on validation / write failure. Defensive --
+// never throws on caller input. The underlying prepare/run is sync per the
+// node:sqlite contract (matches the rest of the navigation module).
+function writeEdge(db, params) {
+  if (!params || typeof params !== 'object') {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const { source_id, target_id, edge_type, properties } = params;
+  if (typeof source_id !== 'string' || source_id.length === 0) {
+    return { ok: false, reason: 'invalid_source_id' };
+  }
+  if (typeof target_id !== 'string' || target_id.length === 0) {
+    return { ok: false, reason: 'invalid_target_id' };
+  }
+  if (typeof edge_type !== 'string' || !ALLOWED_EDGE_TYPES.has(edge_type)) {
+    return { ok: false, reason: 'invalid_edge_type', detail: String(edge_type).slice(0, 40) };
+  }
+  const props = isPlainObject(properties) ? properties : {};
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  const edgeId = 'edge:' + edge_type + ':' + Date.now() + ':' + crypto.randomBytes(4).toString('hex');
+  try {
+    db.prepare(
+      'INSERT INTO edges (source, target, type, properties) VALUES (?, ?, ?, ?) ' +
+      'ON CONFLICT(source, target, type) DO UPDATE SET properties = excluded.properties'
+    ).run(source_id, target_id, edge_type, propsJson);
+  } catch (e) {
+    return { ok: false, reason: 'edge_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, edge_id: edgeId, type: edge_type, source: source_id, target: target_id };
+}
+
+module.exports = { ALLOWED_EDGE_TYPES, writeEdge };

package/lib/core/navigation/insights.cjs

@@ -339,6 +339,42 @@ function findSurfaceableTensions(db, roomId, opts) {
   return candidates;
 }
 
+/**
+ * Phase 124-01 Plan: firstCapturedLastTouchedBySection
+ * ----------------------------------------------------
+ * For a given section slug (the source_section identity for a folder), return
+ * { first_captured_ms, last_touched_ms, total_events } across all memory_event
+ * rows scoped to that section (source_path === slug OR source_path LIKE slug/%).
+ *
+ * Used by lib/core/feynman/timeline-renderer.cjs for the D-05 summary line
+ * ("first captured {first_iso}, last touched {last_iso}"). Returns nulls + 0
+ * count when the section has zero memory_event rows -- the empty-state cue.
+ *
+ * Canon Part 9: pure SQL read against the local room.db; zero Brain surface;
+ * zero filesystem reads. Canon Part 8-safe by construction.
+ */
+function firstCapturedLastTouchedBySection(db, sectionSlug) {
+  if (!db || typeof db.prepare !== 'function' || typeof sectionSlug !== 'string' || sectionSlug.length === 0) {
+    return { first_captured_ms: null, last_touched_ms: null, total_events: 0 };
+  }
+  try {
+    const row = db.prepare(
+      "SELECT MIN(created_at) AS first_ms, MAX(created_at) AS last_ms, COUNT(*) AS n " +
+      "FROM nodes " +
+      "WHERE type = 'memory_event' " +
+      "AND (source_path = ? OR source_path LIKE ?)"
+    ).get(sectionSlug, sectionSlug + '/%');
+    const total = (row && Number.isFinite(row.n)) ? row.n : 0;
+    return {
+      first_captured_ms: total > 0 && Number.isFinite(row.first_ms) ? row.first_ms : null,
+      last_touched_ms: total > 0 && Number.isFinite(row.last_ms) ? row.last_ms : null,
+      total_events: total,
+    };
+  } catch (_) {
+    return { first_captured_ms: null, last_touched_ms: null, total_events: 0 };
+  }
+}
+
 module.exports = {
   findContradictions,
   findUnsupportedClaims,
@@ -347,4 +383,5 @@ module.exports = {
   findOpenQuestions,
   findRelevantOpportunities,
   findSurfaceableTensions,
+  firstCapturedLastTouchedBySection,
 };

package/lib/core/navigation/memory-events.cjs

@@ -70,6 +70,45 @@ const EVENT_TYPES = Object.freeze(new Set([
   'brain_packet_rejected',
   'brain_response_rejected',
   'brain_legacy_path_used',
+  // Phase 124-02 extension (FEYNMAN.md Temporal Awareness; D-10 telemetry mirror):
+  //   feynman_timeline_refreshed      -> the runner successfully rendered + wrote the
+  //                                      sentinel-bounded ## Timeline (auto) section for one
+  //                                      FEYNMAN.md (per section, per refresh).
+  //   feynman_timeline_refresh_failed -> the runner caught an exception during render or write;
+  //                                      watermark NOT updated; FEYNMAN.md NOT corrupted (atomic
+  //                                      .tmp write means the original is preserved on failure).
+  // Additive extension only; mirrors the Phase 110-02 3-string idiom verbatim. logEvent already
+  // rejects event_type values outside EVENT_TYPES -- so these are accepted only because they
+  // are now IN the Set. Set size grows by 2 (was 35 before Phase 124; now 37 baseline; coexists
+  // with the Phase 125-01 framework_invoked extension which adds +1 in parallel).
+  'feynman_timeline_refreshed',
+  'feynman_timeline_refresh_failed',
+  // Phase 125-01 extension (counter source for D3 continuous investment gradient).
+  // Each /mos:* methodology command run logs one framework_invoked event with payload
+  // {framework, command, timestamp}. computeInvestmentLevel(roomState) projects
+  // COUNT(memory_event WHERE event_type='framework_invoked') -> investment_level.
+  // The actual emission site is a follow-on instrumentation pass (lib/render/render-v2.cjs
+  // or per-command hook); Plan 01 only ships the event_type allowlist entry so
+  // computeInvestmentLevel can call findRecentChanges with this filter and get 0 (cold)
+  // back from a fresh room. The instrumentation is non-blocking for Plan 01 acceptance
+  // since computeInvestmentLevel reads from roomState.framework_invocations (which a
+  // separate caller will populate by calling findRecentChanges + counting); when no
+  // such count is available, the helper returns level: 0 -- the cold-start path.
+  'framework_invoked',
+  // Phase 125-06 extension (D7: F-selector reject/defer become typed graph signal).
+  // Emitted by lib/workflow/selector-decisions.cjs::recordSelectorDecision.
+  // Payload: {decision: 'defer'|'reject', command, framework, reason, edge_semantic,
+  //   expires_at|null, score_at_decision, investment_level_at_decision}. The corresponding
+  //   DEFERRED/REJECTED cascade edge is written via navigation.writeEdge (Plan 00).
+  //   Canon Part 4: every choice is graph data. The F-selector's adaptive-questioning
+  //   surface relies on this signal to apply decay-weight in subsequent rankings.
+  'f_selector_decision',
+  // Phase 125-07 extension (D8: none-fit affordance + ranker-miss capture).
+  // Emitted by lib/workflow/selector-decisions.cjs::recordSelectorMiss.
+  // Payload: {top_k_offered: [{command, score}, ...], user_intent: <verbatim user text>,
+  //   investment_level_at_decision}. NO cascade edge written (miss is temporal-only).
+  //   Canon Part 8: user_intent stays LOCAL; never sent to Brain.
+  'f_selector_miss',
 ]));
 
 function isPlainObject(v) {