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

package/lib/core/navigation/projections.cjs

@@ -0,0 +1,201 @@
+'use strict';
+// Phase 125-01 -- pure projection helpers for f-selector-ranker (Plan 05 consumer).
+// All three functions are pure + synchronous; they project roomState into the
+// three signals D4's scoring formula consumes. No I/O. No Brain calls. No db
+// writes. Database READS via existing navigation primitives only -- no direct
+// room-db access.
+//
+// Canon Part 9: SQL remembers and navigates; these helpers are the "navigate"
+// projections over the local mind that the ranker reads BEFORE making its
+// recommendation. Canon Part 7: extension of navigation/, not modification of
+// navigation.cjs's closed surface. Plan 05 may require these directly from
+// projections.cjs OR via navigation.cjs re-export -- Plan 01 ships the
+// projections; navigation.cjs re-export is OPTIONAL (deferred to Plan 05 if
+// preferred to avoid the closed-surface widening discussion).
+//
+// Function signatures (LOCKED in 125-CONTEXT.md "Function signatures (LOCKED)"):
+//   resolveActiveFrameworks(roomState) -> Array<{name, weight, source}>
+//   resolveHopDepth(roomState)         -> {depth: 1|2|3, rationale: string}
+//   computeInvestmentLevel(roomState)  -> {level: number, label: string}
+//
+// roomState shape (extends the chain-recommender.cjs shape per RESEARCH G-03 + G-04):
+//   {
+//     problemType?: 'UDP'|'IDP'|'WDP'|string,
+//     governing_thought?: string,
+//     activeJtbd?: string,
+//     brainAnchors?: string[],
+//     framework_invocations?: number,    // from COUNT(memory_event WHERE event_type='framework_invoked')
+//     feedsIntoEdges?: Edge[],
+//     brainSection?: object,
+//     brainSections?: object,
+//     recentFrameworks?: string[],       // from findRecentChanges memory_event 'framework_invoked'
+//   }
+
+// Common frameworks in the Brain teaching graph -- used as substring hints
+// when extracting from governing_thought free-text. NOT exhaustive (the Brain
+// has 100+ frameworks); just the high-traffic ones for early-room
+// governing_thought parsing. Plan 05 may extend this list or replace with a
+// registry-derived superset; the projection helper is just a substring scan.
+const KNOWN_FRAMEWORK_HINTS = Object.freeze([
+  'Beautiful Question Framework', 'Mullins 7 Domains', 'SWOT', 'Porter Five Forces',
+  'JTBD', 'Jobs to be Done', 'Lean Canvas', 'Business Model Canvas',
+  'Six Thinking Hats', 'Cynefin', 'Root Cause Analysis', 'First Principles',
+  'Wardley Map', 'OKR', 'Scenario Planning', 'Design Thinking',
+]);
+
+function _extractFrameworkFromThought(text) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  for (const fw of KNOWN_FRAMEWORK_HINTS) {
+    if (text.indexOf(fw) !== -1) return fw;
+  }
+  return null;
+}
+
+// Resolve a JTBD id to a framework name via:
+//   jtbd-taxonomy.json (entry.methodology_hooks[0]) -> command slug
+//   command-registry.json (commands[].command) -> first frameworks[]
+// Synchronous, fs-only read. Returns null on any failure -- never throws.
+// Mirrors lib/brain/chain-recommender.cjs::_jtbdToFramework (same fs pattern,
+// same fail-soft contract). Plan 05 may share the registry via injection if
+// it wants to centralize the cache; Plan 01 just reads.
+function _jtbdToFramework(activeJtbd) {
+  if (typeof activeJtbd !== 'string' || activeJtbd.length === 0) return null;
+  const path = require('node:path');
+  const fs = require('node:fs');
+  const TAXONOMY_PATH = path.join(__dirname, '..', '..', 'hmi', 'jtbd-taxonomy.json');
+  const REGISTRY_PATH = path.join(__dirname, '..', '..', '..', 'data', 'command-registry.json');
+  let tax;
+  let reg;
+  try { tax = JSON.parse(fs.readFileSync(TAXONOMY_PATH, 'utf8')); } catch (_e) { return null; }
+  try { reg = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8')); } catch (_e) { return null; }
+  const entry = (tax.entries || []).find((e) => e && e.id === activeJtbd);
+  if (!entry || !Array.isArray(entry.methodology_hooks) || entry.methodology_hooks.length === 0) return null;
+  const firstHook = entry.methodology_hooks[0]; // e.g. '/mos:beautiful-question' or 'mos:beautiful-question'
+  if (typeof firstHook !== 'string') return null;
+  const parts = firstHook.split(':');
+  if (parts.length < 2) return null;
+  const slug = parts.slice(1).join(':');
+  const cmd = (reg.commands || []).find((c) => c && typeof c.command === 'string' && c.command.split(':').slice(1).join(':') === slug);
+  return (cmd && Array.isArray(cmd.frameworks) && cmd.frameworks.length > 0) ? cmd.frameworks[0] : null;
+}
+
+// D1 -- Active-framework multi-signal projection.
+// Precedence (highest -> lowest weight):
+//   1.00  governing_thought  (CONTEXT signal, Phase 90)
+//   0.75  activeJtbd         (INTENT signal, /mos:jtbd via taxonomy)
+//   0.50  brainAnchors       (MEMORY signal, BRAIN.md anchors per Phase 90)
+//   0.25  recentFrameworks   (TEMPORAL signal, memory_event 'framework_invoked' recency)
+// First-write-wins per framework name (a framework already claimed by a higher
+// signal does NOT also appear at a lower one). Empty array on empty roomState.
+function resolveActiveFrameworks(roomState) {
+  if (!roomState || typeof roomState !== 'object') return [];
+  const out = new Map(); // name -> {name, weight, source}
+
+  // 1. governing_thought (CONTEXT signal, weight 1.0)
+  if (typeof roomState.governing_thought === 'string' && roomState.governing_thought.length > 0) {
+    const fw = _extractFrameworkFromThought(roomState.governing_thought);
+    if (fw) out.set(fw, { name: fw, weight: 1.0, source: 'governing_thought' });
+  }
+
+  // 2. activeJtbd (INTENT signal, weight 0.75)
+  if (typeof roomState.activeJtbd === 'string' && roomState.activeJtbd.length > 0) {
+    const fw = _jtbdToFramework(roomState.activeJtbd);
+    if (fw && !out.has(fw)) {
+      out.set(fw, { name: fw, weight: 0.75, source: 'activeJtbd' });
+    }
+  }
+
+  // 3. BRAIN.md anchors (MEMORY signal, weight 0.5)
+  if (Array.isArray(roomState.brainAnchors)) {
+    for (const a of roomState.brainAnchors) {
+      if (typeof a === 'string' && a.length > 0 && !out.has(a)) {
+        out.set(a, { name: a, weight: 0.5, source: 'brain_md' });
+      }
+    }
+  }
+
+  // 4. memory_event recency (TEMPORAL signal, weight 0.25)
+  if (Array.isArray(roomState.recentFrameworks)) {
+    for (const a of roomState.recentFrameworks) {
+      if (typeof a === 'string' && a.length > 0 && !out.has(a)) {
+        out.set(a, { name: a, weight: 0.25, source: 'memory_event' });
+      }
+    }
+  }
+
+  return Array.from(out.values()).sort((a, b) => b.weight - a.weight);
+}
+
+// D2 -- Variable hop depth, context-driven.
+// Defaults to depth 3 (WIDE) on ambiguity per CONTEXT.md.
+//   depth 1: WDP + strong governing_thought (execution mode)
+//   depth 2: IDP (exploratory mode); or WDP without governing_thought
+//   depth 3: wicked / undefined / no anchor (default WIDE)
+function resolveHopDepth(roomState) {
+  if (!roomState || typeof roomState !== 'object') {
+    return { depth: 3, rationale: 'no roomState provided; defaulting WIDE on ambiguity' };
+  }
+  const problemType = roomState.problemType;
+  const hasGoverningThought =
+    typeof roomState.governing_thought === 'string' && roomState.governing_thought.length > 0;
+  if (problemType === 'WDP' && hasGoverningThought) {
+    return {
+      depth: 1,
+      rationale: 'well-defined state with strong governing_thought; execution mode',
+    };
+  }
+  if (problemType === 'IDP') {
+    return {
+      depth: 2,
+      rationale: 'ill-defined state; evolving governing_thought; exploratory mode',
+    };
+  }
+  if (problemType === 'WDP') {
+    return {
+      depth: 2,
+      rationale: 'well-defined problemType but no governing_thought; moderate slice',
+    };
+  }
+  return {
+    depth: 3,
+    rationale: 'wicked or undefined state; no anchor; defaulting WIDE on ambiguity',
+  };
+}
+
+// D3 -- Continuous investment gradient.
+//   level = min(1.0, max(0.0, framework_invocations / 10))
+//   level === 0       -> "fresh room, ranking with Brain priors"
+//   0 < level < 0.5   -> "warming up: Brain + early local signal"
+//   0.5 <= level < 1  -> "balanced: Brain + memory equal weight"
+//   level === 1.0     -> "full local scoring with Brain confidence"
+// Caps at 1.0 for >= 10 invocations; floors at 0.0 for missing or negative
+// counter. Drives D4's scoring formula:
+//   score = brain_confidence*0.40 + (1-recency_decay)*0.30*investment_level
+//         + problem_type_bind*0.30*investment_level
+//   (normalized to 0..1)
+function computeInvestmentLevel(roomState) {
+  const raw =
+    roomState && typeof roomState === 'object' && typeof roomState.framework_invocations === 'number'
+      ? roomState.framework_invocations
+      : 0;
+  const level = Math.min(1.0, Math.max(0.0, raw / 10));
+  let label;
+  if (level === 0) {
+    label = 'fresh room, ranking with Brain priors';
+  } else if (level < 0.5) {
+    label = 'warming up: Brain + early local signal';
+  } else if (level < 1.0) {
+    label = 'balanced: Brain + memory equal weight';
+  } else {
+    label = 'full local scoring with Brain confidence';
+  }
+  return { level, label };
+}
+
+module.exports = {
+  resolveActiveFrameworks,
+  resolveHopDepth,
+  computeInvestmentLevel,
+  // Test seam (private; used by lib/memory/navigation-projections.test.cjs only).
+  _test: { _extractFrameworkFromThought, _jtbdToFramework, KNOWN_FRAMEWORK_HINTS },
+};

package/lib/core/navigation.cjs

@@ -10,6 +10,16 @@
 // re-exports those plus internal helpers as needed) requires canon amendment.
 // Canon Part 9: navigation IS the local mind; this is the only module callers should
 // require for graph reads, ranking, packet building, and truth-state promotion.
+//
+// Phase 125-00 amendment (Pass 3 GAP-2 resolution): writeEdge added as a thin
+// re-export on the navigation surface. Additive extension per the Phase 110-03
+// logMemoryEvent precedent (and the Phase 124-01 firstCapturedLastTouchedBySection
+// precedent shipped between 110-03 and here). The closed DOCUMENTED 13-function
+// API is unchanged in spirit -- additive re-exports of internal helpers are
+// needed for the Plan 06 selector-decisions surface to write typed cascade edges
+// (DEFERRED / REJECTED per CONTEXT.md D7) without bypassing the chokepoint.
+// Canon Part 4 binding: every choice is graph data; writeEdge is the primitive
+// that lets the F-selector ranker emit those choices as typed edges.
 
 const focus = require('./navigation/focus.cjs');
 const neighborhoodMod = require('./navigation/neighborhood.cjs');
@@ -19,6 +29,7 @@ const insights = require('./navigation/insights.cjs');
 const packet = require('./navigation/packet.cjs');
 const ingestion = require('./navigation/ingestion.cjs');
 const roomHome = require('./navigation/room-home.cjs');
+const edges = require('./navigation/edges.cjs');
 
 function notImplementedYet(name, plan) {
   return function () {
@@ -63,4 +74,18 @@ module.exports = {
   //   reaching into the internal navigation/memory-events.cjs. The closed navigation surface is
   //   the DOCUMENTED 13-function API; the implementation re-exports internal helpers as needed.)
   logMemoryEvent: memoryEvents.logEvent,
+
+  // First-captured / last-touched scalars by section (Phase 124-01 -- a thin re-export so
+  //   lib/core/feynman/timeline-renderer.cjs can compose its D-05 summary line over the
+  //   memory_event log without reaching into the internal navigation/insights.cjs. The closed
+  //   navigation surface is the DOCUMENTED 13-function API; the implementation re-exports
+  //   internal helpers as needed -- same pattern as the Phase 110-03 logMemoryEvent re-export.)
+  firstCapturedLastTouchedBySection: insights.firstCapturedLastTouchedBySection,
+
+  // Edge-write primitive (Phase 125-00 -- Pass 3 GAP-2 resolution; D7 typed cascade edge
+  //   surface for F.1 defer / F.2 reject. Allowlist gated on ALLOWED_EDGE_TYPES Set in
+  //   navigation/edges.cjs. Plan 06 selector-decisions.cjs is the first consumer; Phase
+  //   116/117/118 will extend the allowlist additively for tension / auto-explore /
+  //   MVA edges. Same additive-re-export pattern as logMemoryEvent + firstCapturedLastTouchedBySection.)
+  writeEdge: edges.writeEdge,
 };

package/lib/mcp/larry-server-instructions.md

@@ -1,6 +1,6 @@
 # Larry -- MCP Server Instructions
 
-You are Larry, a thinking partner modeled on Prof. Lawrence Aronhime (30+ years teaching innovation at Johns Hopkins). NOT a textbook, NOT a framework dispenser. If your response looks like a PDF, start over.
+You are Larry, a thinking partner modeled on Prof. Lawrence Aronhime (30+ years teaching innovation). NOT a textbook, NOT a framework dispenser. If your response looks like a PDF, start over.
 
 ## Voice
 

package/lib/memory/brain-cypher-chain-slice.test.cjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Phase 125-02 -- Brain Cypher chain slice (framework_chain_hint) tests.
+ *
+ * Run: node --test lib/memory/brain-cypher-chain-slice.test.cjs
+ * Exit 0 on pass. Uses node:test + node:assert/strict.
+ *
+ * Coverage maps 1:1 to 125-02-PLAN.md Task 1 <behavior> Tests 1-10:
+ *   1. Happy-path: 3 rows -> 3 edges, slice_scope=2, snapshot_id non-null.
+ *   2. LIMIT 50 verbatim in the Cypher template constant.
+ *   3. Sanitization called on each framework name; bound value is sanitized.
+ *   4. max_hops bound to 1..3 enum (0 and 4 degrade; 1, 2, 3 valid).
+ *   5. Empty active_frameworks short-circuits (no Brain call).
+ *   6. Brain unreachable (isAvailable=false) degrades.
+ *   7. Brain throws degrades (slice_rationale carries brain_query_failed).
+ *   8. Result mapping: 5 fields propagate verbatim.
+ *   9. Null tolerance (G-05): null confidence + null transform_description preserved.
+ *  10. brain_snapshot_id is sha256 hash of the JSON-stringified raw rows.
+ *
+ * Plus Canon Part 8 grep audit: the Cypher template contains zero user-content
+ * tokens (no roomDir, no artifact, no body, no transcript token).
+ */
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+
+const {
+  fetchFrameworkChainSlice,
+  FRAMEWORK_CHAIN_SLICE_CYPHER,
+  _test,
+} = require('/home/jsagi/MindrianOS-Plugin/lib/brain/framework-chain-slice.cjs');
+
+// Build a mock brainClient with stubbed isAvailable + query + _test seam.
+// sanitizationCalls records every arg passed to sanitizeCypherInput so the
+// test can assert call counts + bound-value equivalence.
+function makeMockClient(opts) {
+  const o = opts || {};
+  const sanitizationCalls = [];
+  const queryInvocations = [];
+  const sanitizer = function (v) {
+    sanitizationCalls.push(v);
+    // Match the shipped whitelist exactly: [a-zA-Z0-9 ._-]
+    return String(v == null ? '' : v).replace(/[^a-zA-Z0-9 ._-]/g, '');
+  };
+  const isAvailable = (typeof o.available === 'boolean') ? o.available : true;
+  const queryFn = (typeof o.queryFn === 'function')
+    ? o.queryFn
+    : (async function () { return []; });
+  return {
+    isAvailable: function () { return isAvailable; },
+    query: async function (cypher, params) {
+      queryInvocations.push({ cypher: cypher, params: params });
+      return queryFn(cypher, params);
+    },
+    _test: {
+      sanitizeCypherInput: sanitizer,
+    },
+    // Exposed on the mock for the test to inspect (not on real brain-client).
+    _sanitizationCalls: sanitizationCalls,
+    _queryInvocations: queryInvocations,
+  };
+}
+
+// ---------------------------------------------------------------- Test 2 (FIRST,
+// pure-constant check; runs without any async).
+
+test('Test 2: Cypher template constant contains LIMIT 50 verbatim', function () {
+  assert.ok(
+    typeof FRAMEWORK_CHAIN_SLICE_CYPHER === 'string'
+      && FRAMEWORK_CHAIN_SLICE_CYPHER.length > 0,
+    'FRAMEWORK_CHAIN_SLICE_CYPHER must be a non-empty string'
+  );
+  assert.ok(
+    FRAMEWORK_CHAIN_SLICE_CYPHER.includes('LIMIT 50'),
+    'FRAMEWORK_CHAIN_SLICE_CYPHER must contain literal "LIMIT 50"'
+  );
+  // Bonus: the parameterized hop range marker.
+  assert.ok(
+    FRAMEWORK_CHAIN_SLICE_CYPHER.includes('FEEDS_INTO*1..$max_hops'),
+    'Cypher must include parameterized hop range "FEEDS_INTO*1..$max_hops"'
+  );
+  // Canon Part 8 grep: no user-content tokens in the template.
+  const forbidden = ['roomDir', 'artifact', 'body', 'transcript', 'roomSlug'];
+  for (const tok of forbidden) {
+    assert.ok(
+      !FRAMEWORK_CHAIN_SLICE_CYPHER.includes(tok),
+      'Cypher must not contain user-content token "' + tok + '"'
+    );
+  }
+  // Read-only: no write keywords in the Cypher template.
+  const writeKeywords = ['MERGE', 'CREATE', 'DELETE', 'SET ', 'REMOVE'];
+  for (const kw of writeKeywords) {
+    assert.ok(
+      !FRAMEWORK_CHAIN_SLICE_CYPHER.includes(kw),
+      'Cypher must be read-only (no "' + kw + '")'
+    );
+  }
+});
+
+// ---------------------------------------------------------------- Test 1
+
+test('Test 1: happy-path returns 3 mapped edges + slice_scope=2 + non-null snapshot_id', async function () {
+  const rows = [
+    { from: 'A', to: 'B', confidence: 0.9, transform_description: 'a->b', hop_distance: 1 },
+    { from: 'A', to: 'C', confidence: 0.7, transform_description: 'a->c', hop_distance: 2 },
+    { from: 'B', to: 'D', confidence: 0.8, transform_description: 'b->d', hop_distance: 2 },
+  ];
+  const mock = makeMockClient({ queryFn: async function () { return rows; } });
+  const result = await fetchFrameworkChainSlice({
+    active_frameworks: ['Beautiful Question Framework'],
+    max_hops: 2,
+    brainClient: mock,
+  });
+  assert.equal(Array.isArray(result.edges), true);
+  assert.equal(result.edges.length, 3);
+  assert.equal(result.slice_scope, 2);
+  assert.equal(typeof result.brain_snapshot_id, 'string');
+  assert.equal(result.brain_snapshot_id.length, 64); // sha256 hex
+  assert.ok(result.slice_rationale.includes('brain_reachable'));
+  assert.equal(typeof result.fetched_at, 'string');
+  // ISO 8601 sanity check.
+  assert.ok(/^\d{4}-\d{2}-\d{2}T/.test(result.fetched_at));
+});
+
+// ---------------------------------------------------------------- Test 3
+
+test('Test 3: sanitization called for every framework name; bound value is sanitized', async function () {
+  const mock = makeMockClient({ queryFn: async function () { return []; } });
+  const dangerous = "SWOT; DROP TABLE x";
+  await fetchFrameworkChainSlice({
+    active_frameworks: [dangerous, 'Beautiful Question Framework'],
+    max_hops: 1,
+    brainClient: mock,
+  });
+  // Sanitizer was called on each name.
+  assert.equal(mock._sanitizationCalls.length, 2);
+  assert.equal(mock._sanitizationCalls[0], dangerous);
+  // The bound active_frameworks param contains the SANITIZED string (no `;`).
+  assert.equal(mock._queryInvocations.length, 1);
+  const bound = mock._queryInvocations[0].params.active_frameworks;
+  assert.ok(Array.isArray(bound));
+  assert.ok(!bound[0].includes(';'), 'sanitized value must not contain ";"');
+  // The whitelist is [a-zA-Z0-9 ._-] -- letters survive, only the metacharacter
+  // `;` is stripped. The injection vector dies because the bound value is the
+  // sanitizer output (a plain identifier string), not raw user input.
+  assert.equal(bound[0], 'SWOT DROP TABLE x'); // ';' stripped, kept word chars
+  // The second framework name (clean) passes through unchanged.
+  assert.equal(bound[1], 'Beautiful Question Framework');
+});
+
+// ---------------------------------------------------------------- Test 4
+
+test('Test 4: max_hops bound to 1..3 enum; 0 and 4 degrade; 1, 2, 3 valid', async function () {
+  const mock = makeMockClient({ queryFn: async function () { return []; } });
+  // max_hops = 0 -> degraded, no Brain call.
+  let r = await fetchFrameworkChainSlice({
+    active_frameworks: ['X'], max_hops: 0, brainClient: mock,
+  });
+  assert.equal(r.edges.length, 0);
+  assert.ok(r.slice_rationale.includes('invalid_max_hops'));
+  // max_hops = 4 -> degraded.
+  r = await fetchFrameworkChainSlice({
+    active_frameworks: ['X'], max_hops: 4, brainClient: mock,
+  });
+  assert.ok(r.slice_rationale.includes('invalid_max_hops'));
+  // No Brain call should have been made for the two invalid hop counts.
+  assert.equal(mock._queryInvocations.length, 0);
+  // max_hops = 1, 2, 3 -> valid (Brain query issued).
+  for (const hops of [1, 2, 3]) {
+    const m2 = makeMockClient({ queryFn: async function () { return []; } });
+    const ok = await fetchFrameworkChainSlice({
+      active_frameworks: ['X'], max_hops: hops, brainClient: m2,
+    });
+    assert.equal(ok.slice_scope, hops);
+    assert.equal(m2._queryInvocations.length, 1);
+    assert.equal(m2._queryInvocations[0].params.max_hops, hops);
+  }
+});
+
+// ---------------------------------------------------------------- Test 5
+
+test('Test 5: empty active_frameworks short-circuits without Brain call', async function () {
+  const mock = makeMockClient({ queryFn: async function () { return []; } });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: [], max_hops: 2, brainClient: mock,
+  });
+  assert.equal(r.edges.length, 0);
+  assert.equal(r.slice_scope, 2);
+  assert.ok(r.slice_rationale.includes('empty active_frameworks'));
+  assert.equal(r.brain_snapshot_id, null);
+  // Brain query NOT called.
+  assert.equal(mock._queryInvocations.length, 0);
+  assert.equal(mock._sanitizationCalls.length, 0);
+});
+
+// ---------------------------------------------------------------- Test 6
+
+test('Test 6: Brain unreachable (isAvailable=false) degrades; no query call', async function () {
+  const mock = makeMockClient({ available: false });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['Beautiful Question Framework'],
+    max_hops: 3,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 0);
+  assert.equal(r.slice_scope, 3);
+  assert.equal(r.slice_rationale, 'brain_unreachable');
+  assert.equal(r.brain_snapshot_id, null);
+  assert.equal(typeof r.fetched_at, 'string');
+  assert.equal(mock._queryInvocations.length, 0);
+});
+
+// ---------------------------------------------------------------- Test 7
+
+test('Test 7: Brain query throws -> degraded; no exception propagates', async function () {
+  const mock = makeMockClient({
+    queryFn: async function () { throw new Error('connection refused'); },
+  });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['X'],
+    max_hops: 2,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 0);
+  assert.equal(r.slice_scope, 2);
+  assert.ok(
+    r.slice_rationale.includes('brain_query_failed'),
+    'rationale must include brain_query_failed; got: ' + r.slice_rationale
+  );
+  assert.ok(r.slice_rationale.includes('connection refused'));
+  assert.equal(r.brain_snapshot_id, null);
+});
+
+// ---------------------------------------------------------------- Test 8
+
+test('Test 8: result mapping preserves all 5 fields verbatim', async function () {
+  const row = {
+    from: 'SWOT',
+    to: 'Porter Five Forces',
+    confidence: 0.85,
+    transform_description: 'analysis -> strategy',
+    hop_distance: 1,
+  };
+  const mock = makeMockClient({ queryFn: async function () { return [row]; } });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['SWOT'],
+    max_hops: 1,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 1);
+  const e = r.edges[0];
+  assert.equal(e.from, 'SWOT');
+  assert.equal(e.to, 'Porter Five Forces');
+  assert.equal(e.confidence, 0.85);
+  assert.equal(e.transform_description, 'analysis -> strategy');
+  assert.equal(e.hop_distance, 1);
+});
+
+// ---------------------------------------------------------------- Test 9 (G-05)
+
+test('Test 9: null confidence + null transform_description preserved (not defaulted)', async function () {
+  const row = {
+    from: 'A',
+    to: 'B',
+    confidence: null,
+    transform_description: null,
+    hop_distance: 2,
+  };
+  const mock = makeMockClient({ queryFn: async function () { return [row]; } });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['A'],
+    max_hops: 2,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 1);
+  const e = r.edges[0];
+  assert.equal(e.from, 'A');
+  assert.equal(e.to, 'B');
+  // Explicit null preservation per CONTEXT.md G-05 + Plan 04 schema.
+  assert.equal(e.confidence, null);
+  assert.equal(e.transform_description, null);
+  // hop_distance still propagates.
+  assert.equal(e.hop_distance, 2);
+});
+
+// ---------------------------------------------------------------- Test 10
+
+test('Test 10: brain_snapshot_id is sha256 of JSON.stringify(raw rows)', async function () {
+  const rows = [
+    { from: 'A', to: 'B', confidence: 0.5, transform_description: 't', hop_distance: 1 },
+  ];
+  const mock = makeMockClient({ queryFn: async function () { return rows; } });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['A'],
+    max_hops: 1,
+    brainClient: mock,
+  });
+  // Expected hash: sha256 of JSON.stringify(rows) exactly as the implementation
+  // computes it (it is the raw rows after Cypher, before edge-shape mapping).
+  const expected = crypto.createHash('sha256')
+    .update(JSON.stringify(rows), 'utf8')
+    .digest('hex');
+  assert.equal(r.brain_snapshot_id, expected);
+});
+
+// ---------------------------------------------------------------- Bonus: shape-tolerant
+// (the live brain-client returns { records: [] }; this verifies both shapes work).
+
+test('Bonus: { records: [...] } wrapper from brain-client.query is unwrapped', async function () {
+  const rows = [
+    { from: 'X', to: 'Y', confidence: 0.6, transform_description: 'x->y', hop_distance: 1 },
+  ];
+  const mock = makeMockClient({
+    queryFn: async function () { return { records: rows }; },
+  });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['X'],
+    max_hops: 1,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 1);
+  assert.equal(r.edges[0].from, 'X');
+});
+
+// ---------------------------------------------------------------- Bonus: non-array
+// Brain return (e.g. an error payload like { error: 'foo' }) degrades cleanly.
+
+test('Bonus: non-array Brain return degrades cleanly', async function () {
+  const mock = makeMockClient({
+    queryFn: async function () { return { error: 'whatever' }; },
+  });
+  const r = await fetchFrameworkChainSlice({
+    active_frameworks: ['X'],
+    max_hops: 1,
+    brainClient: mock,
+  });
+  assert.equal(r.edges.length, 0);
+  assert.ok(r.slice_rationale.includes('brain_returned_non_array'));
+});
+
+// ---------------------------------------------------------------- Canon Part 8:
+// re-read the module source and grep it for forbidden tokens (defence in depth).
+
+test('Canon Part 8: module source contains zero user-content tokens', function () {
+  const src = fs.readFileSync(
+    '/home/jsagi/MindrianOS-Plugin/lib/brain/framework-chain-slice.cjs',
+    'utf8'
+  );
+  // The Cypher constant has been validated above. Here we audit that the
+  // module never builds the query with user-content fields. The only tokens
+  // forbidden in the Cypher *template* + *param-binding* are listed below.
+  // We scan only the Cypher constant + the param object site.
+  const cypherIdx = src.indexOf('FRAMEWORK_CHAIN_SLICE_CYPHER =');
+  assert.ok(cypherIdx > 0);
+  const cypherBlock = src.slice(cypherIdx, src.indexOf('}', cypherIdx + 200));
+  // Cypher must not embed any user-content token literally.
+  const forbidden = ['roomDir', 'roomSlug', 'transcript', 'artifact_body'];
+  for (const tok of forbidden) {
+    assert.ok(
+      !cypherBlock.includes(tok),
+      'Cypher block must not embed user-content token "' + tok + '"'
+    );
+  }
+});