@mindrian_os/install 1.13.0-beta.11

package/lib/core/navigation/ingestion.cjs

@@ -0,0 +1,82 @@
+'use strict';
+// Phase 109-08 Brain Result Ingestion. Per CONTEXT D-07 + RESEARCH section 8.
+// Canon Part 9 LOAD-BEARING: Brain CAN'T write trusted memory.
+// Every brain_insight row: created_by='brain', review_status='proposed', confirmed_by NULL.
+//
+// Per RESEARCH section 8.1: BEGIN/COMMIT/ROLLBACK transaction; partial failures roll back.
+// Per RESEARCH section 8.3: ONE brain_suggestion_received memory_event per ingestion call,
+// not one per insight. The event's review_status='confirmed' because it records a fact
+// about what happened; created_by='system' because the ingestion code wrote it (not Brain).
+// Per Phase 108 PROVENANCE.md L79-89: post-ingestion the canonical invariant SQL query
+// SELECT id, type, source_path, created_by, confirmed_by FROM nodes
+// WHERE review_status = 'confirmed' AND (confirmed_by IS NULL OR confirmed_by != 'user')
+// MUST NOT return any brain_insight rows. brain_insight nodes are 'proposed', so they
+// trivially satisfy the invariant.
+
+const { logEvent } = require('./memory-events.cjs');
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function storeBrainSuggestions(db, packetResult, sessionId) {
+  if (!isPlainObject(packetResult) || !Array.isArray(packetResult.suggestions) || packetResult.suggestions.length === 0) {
+    return { ok: false, reason: 'no_suggestions' };
+  }
+  const jobId = packetResult.job_id || 'unknown_job';
+  const insightIds = [];
+  db.exec('BEGIN');
+  try {
+    for (const sug of packetResult.suggestions) {
+      const suggestionJobId = sug.job_id || jobId;
+      const suggestionIndex = (sug.suggestion_index !== undefined && sug.suggestion_index !== null) ? sug.suggestion_index : insightIds.length;
+      const insightId = 'brain_insight:' + suggestionJobId + ':' + suggestionIndex;
+      const propsJson = JSON.stringify({
+        summary: typeof sug.summary === 'string' ? sug.summary : '',
+        methodology: typeof sug.methodology === 'string' ? sug.methodology : null,
+        body: typeof sug.body === 'string' ? sug.body : '',
+      });
+      const sourcePath = 'brain:job:' + suggestionJobId;
+      const confidence = typeof sug.confidence === 'number' ? sug.confidence : 0.5;
+      const nowMs = Date.now();
+      db.prepare(
+        "INSERT INTO nodes (id, type, properties, source_path, created_by, confidence, review_status, created_at, last_seen_at) " +
+        "VALUES (?, 'brain_insight', ?, ?, 'brain', ?, 'proposed', ?, ?)"
+      ).run(insightId, propsJson, sourcePath, confidence, nowMs, nowMs);
+      insightIds.push(insightId);
+
+      if (Array.isArray(sug.graph_updates_proposed)) {
+        for (const ep of sug.graph_updates_proposed) {
+          if (!ep || typeof ep.source !== 'string' || typeof ep.target !== 'string' || typeof ep.type !== 'string') continue;
+          const edgeProps = JSON.stringify({
+            confidence: typeof ep.confidence === 'number' ? ep.confidence : 0.5,
+            review_status: 'proposed',
+            created_by: 'brain',
+          });
+          db.prepare("INSERT OR IGNORE INTO edges (source, target, type, properties) VALUES (?, ?, ?, ?)").run(ep.source, ep.target, ep.type, edgeProps);
+        }
+      }
+    }
+
+    // ONE memory_event per ingestion call (NOT one per insight; per RESEARCH section 8.3).
+    const evRes = logEvent(db, 'brain_suggestion_received', {
+      session_id: sessionId,
+      insight_ids: insightIds,
+      job_id: jobId,
+      source_path: 'session:' + sessionId,
+      created_by: 'system',
+    });
+    if (!evRes.ok) {
+      db.exec('ROLLBACK');
+      return { ok: false, reason: 'event_log_failed:' + evRes.reason };
+    }
+
+    db.exec('COMMIT');
+    return { ok: true, insightIds, eventId: evRes.eventId };
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_rb) { /* ignore */ }
+    return { ok: false, reason: err.message };
+  }
+}
+
+module.exports = { storeBrainSuggestions };

package/lib/core/navigation/insights.cjs

@@ -0,0 +1,350 @@
+'use strict';
+// Phase 109-05 insight query primitives. 6 of the 7; findRecentChanges lives in memory-events.cjs.
+//
+// Per RESEARCH section 2.5: each query is a single SELECT (with one CTE for findBlockingAssumptions)
+// plus templated explanation rendering. ZERO LLM in the loop. Pure SQL on the local room.db.
+//
+// Per RESEARCH section 11.1 SUPPORTS vs ENABLES: shipped as SEPARATE edge types. findUnsupportedClaims
+// uses a single edge-type filter (NOT EXISTS edge of type 'SUPPORTS'); ENABLES does not satisfy it.
+// Per RESEARCH section 11.2 CausalClaim subsumption: findUnsupportedClaims accepts BOTH type='claim'
+// AND type='CausalClaim' rows via UNION across types (forward-compat with future single-type fold).
+//
+// Canon Part 5: findUnsupportedClaims surfaces missing SUPPORTS edges; findStaleDecisions surfaces
+// decisions older than 30 days; the queries make the evidence bar legible.
+// Canon Part 7: lives under lib/core/navigation/ subdirectory; the chokepoint module navigation.cjs
+// re-exports.
+// Canon Part 8: zero Brain queries; pure SQL on the local room.db.
+// Canon Part 9: SELECT supersedes folder scanning; templated explanation renders the typed edge
+// labels as the explanation substrate.
+
+const path = require('node:path');
+const { getNeighborhood } = require('./neighborhood.cjs');
+const { renderExplanation } = require('./explanation.cjs');
+
+function loadJtbd(roomDir, mocks) {
+  if (mocks && mocks.jtbd) return mocks.jtbd;
+  try {
+    return require(path.resolve(__dirname, '..', '..', 'hmi', 'jtbd-state.cjs'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function jaccard(a, b) {
+  const setA = new Set(Array.isArray(a) ? a : []);
+  const setB = new Set(Array.isArray(b) ? b : []);
+  if (setA.size === 0 && setB.size === 0) return 0;
+  let inter = 0;
+  for (const x of setA) if (setB.has(x)) inter++;
+  const union = setA.size + setB.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+function findContradictions(db, focusNodeId) {
+  const exists = db.prepare('SELECT 1 AS x FROM nodes WHERE id = ?').get(focusNodeId);
+  if (!exists) return [];
+  // Walk the neighborhood; collect node ids reachable from focus.
+  const neighbors = getNeighborhood(db, focusNodeId, { maxDepth: 2, topK: 200 });
+  const reachable = new Set([focusNodeId]);
+  for (const n of neighbors) reachable.add(n.id);
+  // Find edges of type CONTRADICTS where both endpoints are in the reachable set.
+  const ids = Array.from(reachable);
+  const placeholders = ids.map(() => '?').join(',');
+  const rows = db.prepare(
+    "SELECT e.source AS s, e.target AS t, n_a.type AS s_type, n_b.type AS t_type "
+    + "FROM edges e "
+    + "JOIN nodes n_a ON n_a.id = e.source "
+    + "JOIN nodes n_b ON n_b.id = e.target "
+    + "WHERE e.type = 'CONTRADICTS' AND e.source IN (" + placeholders + ") AND e.target IN (" + placeholders + ")"
+  ).all(...ids, ...ids);
+  return rows.map((row) => ({
+    claimA: { id: row.s, type: row.s_type },
+    claimB: { id: row.t, type: row.t_type },
+    edgePath: [row.s, row.t],
+    explanation: renderExplanation('contradiction', { claimA: row.s, claimB: row.t, depth: 1 }),
+  }));
+}
+
+function findUnsupportedClaims(db, roomId) {
+  // Per RESEARCH section 11.2 CausalClaim subsumption: UNION across both types.
+  // Per RESEARCH section 11.1 SUPPORTS-only filter: NOT EXISTS edge of type SUPPORTS.
+  const rows = db.prepare(
+    "SELECT n.id, n.type, n.source_path, n.review_status, n.last_seen_at "
+    + "FROM nodes n "
+    + "WHERE n.type IN ('claim','CausalClaim') "
+    + "AND n.review_status IN ('confirmed','needs_evidence') "
+    + "AND NOT EXISTS (SELECT 1 FROM edges e WHERE e.target = n.id AND e.type = 'SUPPORTS')"
+  ).all();
+  return rows.map((r) => ({
+    claim: { id: r.id, type: r.type, sourcePath: r.source_path, reviewStatus: r.review_status, lastSeenAt: r.last_seen_at },
+    missingEvidenceFor: r.id,
+    explanation: renderExplanation('unsupported', { claim: r.id, reviewStatus: r.review_status, lastSeenAt: r.last_seen_at }),
+  }));
+}
+
+function findBlockingAssumptions(db, goalNodeId) {
+  const exists = db.prepare('SELECT 1 AS x FROM nodes WHERE id = ?').get(goalNodeId);
+  if (!exists) return [];
+  // Recursive cascade: walk DEPENDS_ON + ASSUMES edges from goal upstream.
+  // Cascade direction: goal node has outgoing DEPENDS_ON / ASSUMES edges to assumptions.
+  // Walk source -> target where current cascade member is the source.
+  const rows = db.prepare(
+    "WITH RECURSIVE cascade(id, depth) AS ( "
+    + "SELECT ? AS id, 0 AS depth "
+    + "UNION ALL "
+    + "SELECT e.target, c.depth + 1 FROM edges e JOIN cascade c ON e.source = c.id "
+    + "WHERE e.type IN ('DEPENDS_ON', 'ASSUMES') AND c.depth < 5 "
+    + ") "
+    + "SELECT DISTINCT n.id, n.type, n.source_path, n.confidence, n.review_status, c.depth "
+    + "FROM nodes n JOIN cascade c ON c.id = n.id "
+    + "WHERE n.type = 'assumption' AND n.review_status IN ('proposed', 'needs_evidence')"
+  ).all(goalNodeId);
+  return rows.map((r) => ({
+    assumption: { id: r.id, type: r.type, sourcePath: r.source_path, confidence: r.confidence, reviewStatus: r.review_status },
+    blocksGoal: { id: goalNodeId },
+    cascadePath: [r.id, goalNodeId],
+    explanation: renderExplanation('blocking', { assumption: r.id, goal: goalNodeId, cascadePath: [r.id, goalNodeId] }),
+  }));
+}
+
+function findStaleDecisions(db, roomId, opts) {
+  // Per RESEARCH section 2.5 simplification: 30 days old AND review_status='confirmed'.
+  // The opts.staleAfterSessions parameter is preserved for API compatibility but is
+  // interpreted as the 30-day threshold (RESEARCH lines 540 simplification).
+  const thresholdMs = Date.now() - 30 * 24 * 60 * 60 * 1000;
+  const rows = db.prepare(
+    "SELECT n.id, n.type, n.source_path, n.last_seen_at, n.review_status "
+    + "FROM nodes n "
+    + "WHERE n.type = 'decision' AND n.review_status = 'confirmed' AND n.last_seen_at < ?"
+  ).all(thresholdMs);
+  return rows.map((r) => ({
+    decision: { id: r.id, type: r.type, sourcePath: r.source_path, reviewStatus: r.review_status },
+    lastSeenAt: r.last_seen_at,
+    explanation: renderExplanation('stale', { decision: r.id, lastSeenAt: r.last_seen_at }),
+  }));
+}
+
+function findOpenQuestions(db, roomId) {
+  const rows = db.prepare(
+    "SELECT n.id, n.source_path, n.created_at "
+    + "FROM nodes n "
+    + "WHERE n.type = 'open_question' "
+    + "AND n.review_status IN ('proposed', 'confirmed') "
+    + "AND NOT EXISTS (SELECT 1 FROM edges e WHERE e.target = n.id AND e.type IN ('SUPPORTS', 'EVIDENCES'))"
+  ).all();
+  return rows.map((r) => ({
+    question: { id: r.id, sourcePath: r.source_path, createdAt: r.created_at },
+    createdAt: r.created_at,
+    explanation: renderExplanation('open', { question: r.id, createdAt: r.created_at }),
+  }));
+}
+
+function hsiBand(score) {
+  const s = Number(score) || 0;
+  if (s >= 70) return 'high';
+  if (s >= 40) return 'medium';
+  return 'low';
+}
+
+function findRelevantOpportunities(db, focusNodeId, opts) {
+  const options = opts || {};
+  const topK = Number.isInteger(options.topK) && options.topK > 0 ? options.topK : 5;
+  const wHsi = typeof options.weightHsi === 'number' ? options.weightHsi : 0.5;
+  const wDist = typeof options.weightDistance === 'number' ? options.weightDistance : 0.3;
+  const wJtbd = typeof options.weightJtbd === 'number' ? options.weightJtbd : 0.2;
+  const exists = db.prepare('SELECT 1 AS x FROM nodes WHERE id = ?').get(focusNodeId);
+  if (!exists) return [];
+
+  const neighbors = getNeighborhood(db, focusNodeId, { maxDepth: 3, topK: 200 });
+  const distMap = new Map();
+  for (const n of neighbors) {
+    if (n.type === 'opportunity') distMap.set(n.id, n.depth);
+  }
+
+  // Also include any opportunity nodes room-wide; the Opportunity Bank is "always ambient"
+  // per Canon Part 2 so we score every opportunity, not just neighborhood-reachable ones.
+  // Distance falls back to a high depth penalty when the opportunity is not in the neighborhood.
+  const allOpps = db.prepare(
+    "SELECT id, "
+    + "json_extract(properties, '$.hsi_score') AS hsi_score, "
+    + "json_extract(properties, '$.tags') AS tags_json, "
+    + "source_path, review_status "
+    + "FROM nodes WHERE type = 'opportunity' AND review_status IN ('proposed','confirmed','validated')"
+  ).all();
+
+  // Per Plan 109-02 focus.cjs precedent: jtbd is read via getCurrent and the test mock returns
+  // { current: { id, tags } }. The real jtbd-state.cjs requires a roomDir; when no _mocks seam
+  // is provided AND no roomDir is configured (the common navigation API call shape), we treat
+  // active JTBD as absent (jtbdScore = 0 across the board) rather than crash on path.join(null).
+  const roomDir = typeof options.roomDir === 'string' ? options.roomDir : null;
+  const jtbdMod = loadJtbd(roomDir, options._mocks);
+  let jtbd = null;
+  if (jtbdMod && (options._mocks && options._mocks.jtbd || roomDir)) {
+    try {
+      jtbd = jtbdMod.getCurrent(roomDir);
+    } catch (_) {
+      jtbd = null;
+    }
+  }
+  const activeTags = jtbd && jtbd.current && Array.isArray(jtbd.current.tags) ? jtbd.current.tags : [];
+
+  const ranked = allOpps.map((row) => {
+    const tags = row.tags_json ? JSON.parse(row.tags_json) : [];
+    const hsi = (Number(row.hsi_score) || 0) / 100;
+    const depth = distMap.has(row.id) ? distMap.get(row.id) : 99;
+    const distScore = 1.0 / (1 + depth);
+    const jtbdScore = activeTags.length > 0 ? jaccard(activeTags, tags) : 0;
+    const composite = wHsi * hsi + wDist * distScore + wJtbd * jtbdScore;
+    return {
+      opportunityId: row.id,
+      hsiScore: Number(row.hsi_score) || 0,
+      graphDistance: depth,
+      jtbdMatch: jtbdScore,
+      compositeScore: Math.round(composite * 1000) / 1000,
+      tags,
+      sourcePath: row.source_path,
+      explanation: renderExplanation('opportunity', { opportunityId: row.id, hsiBand: hsiBand(row.hsi_score), jtbdMatch: jtbdScore, depth }),
+    };
+  });
+  ranked.sort((a, b) => b.compositeScore - a.compositeScore);
+  return ranked.slice(0, topK);
+}
+
+/**
+ * Phase 116-01 Wave 1 -- room-wide tension candidate query joining JSONL decay state.
+ *
+ * Returns deterministic-id candidates derived from CONTRADICTS edges (priority 1)
+ * with fallback to CONVERGES edges (priority 2) per CONTEXT D-03b. Filters out
+ * tension_ids whose JSONL state shows surfacing_count >= 3 OR state IN
+ * ('resolved','dropped') so a resolved or decayed tension never re-surfaces.
+ *
+ * Sync. Defensive. Returns [] on empty / missing graph or missing roomSlug.
+ * Reads JSONL state via lib/memory/pending-tension-store.cjs (lazy require so a
+ * test substituting that module in require.cache wins).
+ *
+ * Per RESEARCH OQ-1: this function lives ON the closed navigation surface
+ * (re-exported by lib/core/navigation.cjs) so the SessionStart hook reads
+ * tensions through the Phase 109 D-06 chokepoint, NOT around it.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} roomId  preserved for API symmetry; unused in v1
+ * @param {object} opts
+ * @param {string}  opts.roomSlug              required for JSONL state filter
+ * @param {number}  [opts.limit=10]            max candidates returned
+ * @param {boolean} [opts.includeConvergence]  default true (D-03b priority 2)
+ * @returns {Array<object>}
+ */
+function findSurfaceableTensions(db, roomId, opts) {
+  const options = (opts && typeof opts === 'object') ? opts : {};
+  const roomSlug = (typeof options.roomSlug === 'string' && options.roomSlug.length > 0)
+    ? options.roomSlug
+    : null;
+  const limit = (Number.isInteger(options.limit) && options.limit > 0) ? options.limit : 10;
+  const includeConvergence = (options.includeConvergence !== false); // default true
+
+  if (!db || !roomSlug) return [];
+
+  // Lazy require so tests can mock pending-tension-store via require.cache.
+  let pendingStore = null;
+  try {
+    pendingStore = require('../../memory/pending-tension-store.cjs');
+  } catch (_e) {
+    pendingStore = null;
+  }
+
+  // Build excluded-id Set from JSONL state (D-03b filter).
+  const excluded = new Set();
+  if (pendingStore && typeof pendingStore.readTensions === 'function') {
+    try {
+      const entries = pendingStore.readTensions(roomSlug);
+      for (const e of entries) {
+        if (!e || typeof e.tension_id !== 'string') continue;
+        if (e.surfacing_count >= 3 || e.state === 'resolved' || e.state === 'dropped') {
+          excluded.add(e.tension_id);
+        }
+      }
+    } catch (_e) {
+      // graceful: empty exclusion set on JSONL read failure
+    }
+  }
+
+  // Deterministic id helper (re-uses pending-tension-store.computeTensionId
+  // when available; falls back to inline sha256 if module load failed).
+  const computeId = (pendingStore && typeof pendingStore.computeTensionId === 'function')
+    ? pendingStore.computeTensionId
+    : function (s, t, ty) {
+        return require('node:crypto')
+          .createHash('sha256')
+          .update(String(s) + '|' + String(t) + '|' + String(ty))
+          .digest('hex')
+          .slice(0, 32);
+      };
+
+  // SELECT helper: returns rows for a given edge type, sorted by created_at DESC.
+  // edges.created_at lives inside properties JSON (lazygraph schema convention);
+  // we use json_extract for the ORDER BY and a LEFT JOIN on nodes to fetch
+  // section names (source_section / source_path) for the candidate context.
+  function selectEdges(edgeType) {
+    try {
+      return db.prepare(
+        "SELECT e.rowid AS edge_id, e.source AS source_node_id, e.target AS target_node_id, " +
+        "e.type AS edge_type, " +
+        "COALESCE(json_extract(e.properties, '$.created_at'), 0) AS created_at, " +
+        "ns.source_path AS source_section, " +
+        "nt.source_path AS target_section " +
+        "FROM edges e " +
+        "LEFT JOIN nodes ns ON ns.id = e.source " +
+        "LEFT JOIN nodes nt ON nt.id = e.target " +
+        "WHERE e.type = ? " +
+        "ORDER BY COALESCE(json_extract(e.properties, '$.created_at'), 0) DESC " +
+        "LIMIT ?"
+      ).all(edgeType, limit * 3); // overfetch then filter
+    } catch (_e) {
+      return [];
+    }
+  }
+
+  function pushCandidates(rows, tensionType, candidates, seen) {
+    for (const r of rows) {
+      const tid = computeId(r.source_node_id, r.target_node_id, tensionType);
+      if (excluded.has(tid) || seen.has(tid)) continue;
+      seen.add(tid);
+      candidates.push({
+        tension_id: tid,
+        tension_type: tensionType,
+        source_node_id: r.source_node_id,
+        target_node_id: r.target_node_id,
+        source_section: r.source_section || '',
+        target_section: r.target_section || '',
+        edge_id: r.edge_id,
+        created_at: r.created_at,
+      });
+      if (candidates.length >= limit) return true;
+    }
+    return false;
+  }
+
+  const candidates = [];
+  const seen = new Set();
+
+  // Priority 1: CONTRADICTS edges DESC.
+  pushCandidates(selectEdges('CONTRADICTS'), 'contradiction', candidates, seen);
+
+  // Priority 2: CONVERGES edges DESC (only when CONTRADICTS yielded nothing AND
+  // includeConvergence is true). Per D-03b, the fallback fires only on empty.
+  if (candidates.length === 0 && includeConvergence) {
+    pushCandidates(selectEdges('CONVERGES'), 'convergence', candidates, seen);
+  }
+
+  return candidates;
+}
+
+module.exports = {
+  findContradictions,
+  findUnsupportedClaims,
+  findBlockingAssumptions,
+  findStaleDecisions,
+  findOpenQuestions,
+  findRelevantOpportunities,
+  findSurfaceableTensions,
+};

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

@@ -0,0 +1,118 @@
+'use strict';
+// Phase 109-03 memory event log primitives. Internal to lib/core/navigation/.
+// Re-exported by lib/core/navigation.cjs (Plan 109-04) as findRecentChanges (closed surface).
+// logEvent is internal (not in the closed 13-function surface); other navigation/* helpers
+// call it directly. Plan 109-02 setFocus writes focus_changed events inline (predates this
+// plan); Plan 109-08 storeBrainSuggestions uses logEvent for brain_suggestion_received.
+
+const crypto = require('node:crypto');
+
+const EVENT_TYPES = Object.freeze(new Set([
+  'node_created',
+  'status_promoted',
+  'status_rejected',
+  'status_stale',
+  'status_superseded',
+  'focus_changed',
+  'brain_query_sent',
+  'brain_suggestion_received',
+  'edge_added',
+  'edge_removed',
+  'opportunity_added',
+  'opportunity_reacted',
+  'opportunity_reflected',
+  'opportunity_answered',
+  'state_alias_migration',
+  // Phase 88.2-00 Wave 0 extension (D-AMEND-02 telemetry mirror, R1-safe, INTERNAL Set)
+  'selector_presentation',
+  'selector_response',
+  'selector_rejection_captured',
+  'f6_round_completed',
+  // Phase 89-07 Wave 0 extension (graph-native HARD RULE; ReverseSalientAgent dual-surface
+  // telemetry mirror per memory feedback_reverse_salient_agent_graph_native.md rule 3).
+  'reverse_salient_detected',
+  'reverse_salient_acted_on',
+  // Phase 116-00 Wave 0 extension (graph-native HARD RULE; unresolved-tension-hook
+  // dual-surface telemetry mirror per memory feedback_reverse_salient_agent_graph_native.md
+  // rule 3, mirroring the 89-07 ReverseSalientAgent pattern).
+  'tension_detected',
+  'tension_surfaced',
+  'tension_resolved',
+  'tension_decayed',
+  'tension_skipped',
+  // Phase 117-00 Wave 0 extension (graph-native HARD RULE; auto-explore-domains
+  // dual-surface telemetry mirror per memory feedback_reverse_salient_agent_graph_native.md
+  // rule 3, mirroring the 116-00 + 89-07-00 ReverseSalientAgent extension pattern).
+  // Per RESEARCH §4.7 + §8.6: 4 auto_explore lifecycle events + 1 Brain-canon-drift event:
+  //   fired (fingerprint detection -> spawn) -> finding_surfaced (drain -> F.1)
+  //   -> user_response (Explore/Skip/Later/Free-text) OR skipped (suppression).
+  //   brain_canon_drift_observed (FourLenses Brain vs FiveLenses Canon; emitted once per
+  //   session by 117-05 emitBrainCanonDrift via this EVENT_TYPES string; size 31 invariant).
+  'auto_explore_fired',
+  'auto_explore_finding_surfaced',
+  'auto_explore_user_response',
+  'auto_explore_skipped',
+  'auto_explore_sanitizer_hit',
+  'brain_canon_drift_observed',
+]));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function logEvent(db, eventType, payload) {
+  if (!EVENT_TYPES.has(eventType)) {
+    return { ok: false, reason: 'invalid_event_type' };
+  }
+  if (!isPlainObject(payload)) {
+    return { ok: false, reason: 'invalid_payload' };
+  }
+  const nowMs = Date.now();
+  const eventId = 'memory_event:' + eventType + ':' + nowMs + ':' + crypto.randomBytes(4).toString('hex');
+  // Merge event_type as top-level key (overrides any caller-supplied event_type to prevent drift).
+  const merged = Object.assign({}, payload, { event_type: eventType });
+  const propsJson = JSON.stringify(merged);
+  const sourcePath = typeof payload.source_path === 'string' ? payload.source_path : 'system:default';
+  const createdBy = typeof payload.created_by === 'string' ? payload.created_by : 'system';
+  try {
+    db.prepare(
+      "INSERT INTO nodes (id, type, properties, source_path, created_by, confidence, review_status, created_at, last_seen_at) " +
+      "VALUES (?, 'memory_event', ?, ?, ?, NULL, 'confirmed', ?, ?)"
+    ).run(eventId, propsJson, sourcePath, createdBy, nowMs, nowMs);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+  return { ok: true, eventId };
+}
+
+function findRecentChanges(db, sinceEpochMs, opts) {
+  const options = opts || {};
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 100;
+  const eventTypeFilter = typeof options.eventType === 'string' && EVENT_TYPES.has(options.eventType) ? options.eventType : null;
+
+  let sql =
+    "SELECT n.id, json_extract(n.properties, '$.event_type') AS event_type, " +
+    "json_extract(n.properties, '$.target_node_id') AS target_node_id, " +
+    "n.created_at, n.source_path, n.properties " +
+    "FROM nodes n " +
+    "WHERE n.type = 'memory_event' AND n.created_at > ? ";
+  const params = [sinceEpochMs];
+  if (eventTypeFilter) {
+    sql += "AND json_extract(n.properties, '$.event_type') = ? ";
+    params.push(eventTypeFilter);
+  }
+  sql += "ORDER BY n.created_at DESC LIMIT ?";
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params);
+  return rows.map((r) => ({
+    id: r.id,
+    eventType: r.event_type,
+    targetNodeId: r.target_node_id,
+    createdAt: r.created_at,
+    sourcePath: r.source_path,
+    properties: JSON.parse(r.properties),
+  }));
+}
+
+module.exports = { EVENT_TYPES, logEvent, findRecentChanges };

package/lib/core/navigation/neighborhood.cjs

@@ -0,0 +1,78 @@
+'use strict';
+// Phase 109-04 neighborhood retrieval. The recursive CTE per RESEARCH section 2.1.
+// Frozen edge weights per CONTEXT D-02 lines 113-118.
+//
+// Canon Part 1: getNeighborhood IS the answer to "what is near my focus?"; the
+// navigator never folder-scans again.
+// Canon Part 4: typed edges drive ranking; the edge_path field carries the
+// graph paths that later plans render as explanation strings.
+// Canon Part 7: lives under lib/core/navigation/ subdirectory established by
+// Plan 109-02; the chokepoint module navigation.cjs re-exports.
+// Canon Part 9: SELECT supersedes folder scanning; this is the load-bearing
+// query for the acceptance test.
+
+const NEIGHBORHOOD_SQL = "WITH RECURSIVE neighborhood(id, type, edge_path, depth, edge_type_in, last_seen_at, confidence, source_section, review_status, created_by, source_path) AS ( "
+  + "SELECT n.id, n.type, json_array(n.id) AS edge_path, 0 AS depth, NULL AS edge_type_in, "
+  + "n.last_seen_at, n.confidence, n.source_section, n.review_status, n.created_by, n.source_path "
+  + "FROM nodes n WHERE n.id = :focus_node_id "
+  + "UNION ALL "
+  + "SELECT next_n.id, next_n.type, json_insert(nh.edge_path, '$[#]', next_n.id) AS edge_path, "
+  + "nh.depth + 1 AS depth, e.type AS edge_type_in, "
+  + "next_n.last_seen_at, next_n.confidence, next_n.source_section, next_n.review_status, next_n.created_by, next_n.source_path "
+  + "FROM neighborhood nh JOIN edges e ON e.source = nh.id JOIN nodes next_n ON next_n.id = e.target "
+  + "WHERE nh.depth < :max_depth "
+  + "AND json_array_length(nh.edge_path) < (:max_depth + 1) "
+  + "AND nh.id != next_n.id "
+  + ") "
+  + "SELECT id, type, edge_path, depth, edge_type_in, source_path, review_status, created_by, confidence, last_seen_at, "
+  + "( "
+  + "CASE edge_type_in "
+  + "WHEN 'CONTRADICTS' THEN 1.0 "
+  + "WHEN 'INVALIDATES' THEN 1.0 "
+  + "WHEN 'DEPENDS_ON'  THEN 0.9 "
+  + "WHEN 'ASSUMES'     THEN 0.9 "
+  + "WHEN 'SUPPORTS'    THEN 0.8 "
+  + "WHEN 'EVIDENCES'   THEN 0.8 "
+  + "WHEN 'INFORMS'     THEN 0.6 "
+  + "WHEN 'ENABLES'     THEN 0.6 "
+  + "WHEN 'CONVERGES'   THEN 0.4 "
+  + "WHEN 'MENTIONS_ENTITY' THEN 0.4 "
+  + "ELSE 0.3 "
+  + "END * 0.4 "
+  + "+ MAX(0.0, MIN(1.0, 1.0 - (CAST(strftime('%s','now') AS REAL) * 1000 - last_seen_at) / (1000.0 * 60 * 60 * 24 * 90))) * 0.2 "
+  + "+ COALESCE(confidence, 0.5) * 0.2 "
+  + "+ CASE WHEN source_section = (SELECT source_section FROM nodes WHERE id = :focus_node_id) THEN 1.0 ELSE 0.0 END * 0.2 "
+  + ") AS score "
+  + "FROM neighborhood WHERE depth > 0 ORDER BY score DESC LIMIT :top_k";
+
+function getNeighborhood(db, focusNodeId, opts) {
+  const options = opts || {};
+  const maxDepth = Number.isInteger(options.maxDepth) && options.maxDepth >= 1 ? options.maxDepth : 2;
+  const topK = Number.isInteger(options.topK) && options.topK > 0 ? options.topK : 20;
+
+  // Politely return [] if focus does not exist (avoids letting the CTE return base-case row with no recursion).
+  const exists = db.prepare("SELECT 1 AS x FROM nodes WHERE id = ?").get(focusNodeId);
+  if (!exists) return [];
+
+  const rows = db.prepare(NEIGHBORHOOD_SQL).all({
+    focus_node_id: focusNodeId,
+    max_depth: maxDepth,
+    top_k: topK,
+  });
+
+  return rows.map((r) => ({
+    id: r.id,
+    type: r.type,
+    edgePath: typeof r.edge_path === 'string' ? JSON.parse(r.edge_path) : r.edge_path,
+    depth: r.depth,
+    edgeTypeIn: r.edge_type_in,
+    score: r.score,
+    sourcePath: r.source_path,
+    reviewStatus: r.review_status,
+    createdBy: r.created_by,
+    confidence: r.confidence,
+    lastSeenAt: r.last_seen_at,
+  }));
+}
+
+module.exports = { getNeighborhood, NEIGHBORHOOD_SQL };