@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/lib/core/navigation/planning-artifacts.cjs

@@ -0,0 +1,219 @@
+'use strict';
+/*
+ * Phase 149-01 -- planning-artifacts: the typed planning_artifact + requirement
+ * node-write chokepoint, plus the typed-lineage-edge writer, for the GSD-doc to
+ * local-graph bridge. This is the net-new substrate the reconcile (Plan 02) and
+ * the writer hook (Plan 03) ride on. GAM-01 / GAM-03 / GAM-04.
+ *
+ * This module is an allow-listed navigation submodule (scripts/check-substrate.cjs
+ * regex /^lib\/core\/navigation\// covers it). It takes a db handle owned by the
+ * caller (via lib/core/room-db.cjs openRoomDb) EXACTLY like
+ * lib/core/navigation/lens-nodes.cjs and lib/core/navigation/edges.cjs: it NEVER
+ * requires node:sqlite and NEVER opens room.db itself, so it stays inside the
+ * navigation allow-list with ZERO substrate bypass (GAM-01 substrate-guard floor;
+ * threat T-149-03). The only sibling it requires is ./edges.cjs.
+ *
+ * Exports:
+ *   writePlanningArtifactNode(db, {phase, artifactType, path, status})
+ *                                  -> { ok, node_id } | { ok:false, reason }
+ *   writeRequirementNode(db, {reqId, phase})
+ *                                  -> { ok, node_id } | { ok:false, reason }
+ *   writeLineageEdge(db, {source_id, target_id, edge_type, properties})
+ *                                  -> { ok, ... } | { ok:false, reason }
+ *   ARTIFACT_TYPES                 -> frozen array of the 7 GSD artifact types
+ *   ARTIFACT_NODE_ID(phase, artifactType) -> stable node id
+ *   REQUIREMENT_NODE_ID(reqId)            -> stable node id
+ *
+ * Canon Part 9 v1.5 (AUDIT-NODE CARVE-OUT): planning_artifact + requirement are
+ *   SYSTEM-BOOKKEEPING nodes -- they record what the system DID about the GSD
+ *   planning surface (which artifacts exist, which requirements were declared),
+ *   NOT a truth-claim about the venture. They are NOT in the truth-claim set
+ *   {claim, CausalClaim, assumption, decision, opportunity}. So they MAY carry
+ *   created_by='system' review_status='confirmed' WITHOUT a human byUser; the
+ *   carve-out makes that confirmed-status write canon-legal, not a Part 9 role-5
+ *   violation. Here review_status='confirmed' means write-completed (the artifact
+ *   exists), not human-attributed truth. They never reach the confirmNode
+ *   human-byUser truth-claim path. Mirrors lib/core/navigation/focus.cjs writing
+ *   a focus_changed audit node with created_by='system' review_status='confirmed'
+ *   and lib/core/navigation/lens-nodes.cjs writing a HatState node the same way.
+ *
+ * Canon Part 8: zero network surface. Pure LOCAL SQLite over a caller-owned
+ *   handle. No Brain calls; the artifact BODY never leaves the room. The lineage
+ *   edge properties are ENUM/scalar only (a phase id + an artifact-type enum);
+ *   the artifact prose never lands on a node or edge here.
+ *
+ * Canon Part 7 (reuse before build): writeLineageEdge is a thin pass-through to
+ *   edges.writeEdge -- the existing edge-write primitive gated on the shipped
+ *   ALLOWED_EDGE_TYPES Set. This module adds NO new taxonomy member of its own;
+ *   it CONSTRAINS to the existing LINEAGE subset {FEEDS_INTO, VALIDATES,
+ *   INFORMS} (all members of ALLOWED_EDGE_TYPES), so edges.cjs stays the single
+ *   source of truth for the predicate vocabulary (threat T-149-01).
+ *
+ * NO em-dashes anywhere in this file (CLAUDE.md HARD RULE).
+ */
+
+const edges = require('./edges.cjs');
+const { insertNode } = require('../node-insert.cjs');
+
+// The 7 GSD planning-artifact types (SPEC / CONTEXT / RESEARCH / VALIDATION /
+// PLAN / VERIFICATION / DISCUSSION-LOG). Frozen so callers cannot mutate the
+// closed set; writePlanningArtifactNode validates artifactType against the Set.
+const ARTIFACT_TYPES = Object.freeze([
+  'SPEC',
+  'CONTEXT',
+  'RESEARCH',
+  'VALIDATION',
+  'PLAN',
+  'VERIFICATION',
+  'DISCUSSION-LOG',
+]);
+const ARTIFACT_TYPE_SET = Object.freeze(new Set(ARTIFACT_TYPES));
+
+// The LINEAGE subset writeLineageEdge accepts. Each member is ALSO a member of
+// edges.cjs ALLOWED_EDGE_TYPES (FEEDS_INTO + VALIDATES added at Phase 149-01;
+// INFORMS shipped at Phase 130-01). This is a SUBSET-constraint, not a new
+// taxonomy: a non-lineage-but-real edge type (e.g. DEFERRED) is rejected here
+// even though edges.writeEdge would accept it, and a non-taxonomy type
+// (BOGUS_LINK) is rejected at BOTH layers.
+const LINEAGE_EDGE_TYPES = Object.freeze(['FEEDS_INTO', 'VALIDATES', 'INFORMS']);
+const LINEAGE_EDGE_TYPE_SET = Object.freeze(new Set(LINEAGE_EDGE_TYPES));
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// ARTIFACT_NODE_ID(phase, artifactType) -- the stable id that makes the
+// ON CONFLICT(id) DO UPDATE upsert deduplicate per the GAM-04 idempotence
+// contract. Re-running over the same artifact updates the SAME row, never adds
+// a duplicate.
+function ARTIFACT_NODE_ID(phase, artifactType) {
+  return 'planning_artifact:' + phase + ':' + artifactType;
+}
+
+// REQUIREMENT_NODE_ID(reqId) -- the stable id for a per-requirement node.
+function REQUIREMENT_NODE_ID(reqId) {
+  return 'requirement:' + reqId;
+}
+
+// writePlanningArtifactNode(db, {phase, artifactType, path, status}) -- UPSERT a
+// typed planning_artifact node. Validates artifactType against ARTIFACT_TYPE_SET;
+// JSON.stringify the properties {phase, artifact_type, path, status}; runs the
+// INSERT ... ON CONFLICT(id) DO UPDATE upsert (mirrors lens-nodes.cjs writeHatState
+// verbatim). created_by='system', confidence 1.0, review_status='confirmed' (the
+// Canon Part 9 v1.5 audit-node carve-out). source_path is a LOCAL handle
+// 'planning:'+phase+':'+artifactType, never user prose. Defensive: never throws
+// on caller input; returns { ok:false, reason } on failure.
+function writePlanningArtifactNode(db, params) {
+  if (!isPlainObject(params)) {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const { phase, artifactType, path: artifactPath, status } = params;
+  if (typeof phase !== 'string' || phase.length === 0) {
+    return { ok: false, reason: 'invalid_phase' };
+  }
+  if (typeof artifactType !== 'string' || !ARTIFACT_TYPE_SET.has(artifactType)) {
+    return { ok: false, reason: 'invalid_artifact_type', detail: String(artifactType).slice(0, 40) };
+  }
+  if (typeof artifactPath !== 'string' || artifactPath.length === 0) {
+    return { ok: false, reason: 'invalid_path' };
+  }
+  const props = {
+    phase: phase,
+    artifact_type: artifactType,
+    path: artifactPath,
+    status: typeof status === 'string' ? status : '',
+  };
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  const nodeId = ARTIFACT_NODE_ID(phase, artifactType);
+  const sourcePath = 'planning:' + phase + ':' + artifactType;
+  try {
+    insertNode(db, nodeId, 'planning_artifact', propsJson, {
+      source_path: sourcePath,
+      created_by: 'system',
+      confidence: 1.0,
+      review_status: 'confirmed',
+      // R17-02 (Task 4 Decision 4): 'observation' -- system bookkeeping.
+      epistemic_type: 'observation',
+    });
+  } catch (e) {
+    return { ok: false, reason: 'planning_artifact_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, node_id: nodeId };
+}
+
+// writeRequirementNode(db, {reqId, phase}) -- UPSERT a typed requirement node.
+// Same shape as writePlanningArtifactNode: stable id REQUIREMENT_NODE_ID(reqId),
+// type 'requirement', system-bookkeeping carve-out (created_by='system',
+// review_status='confirmed'), properties {req_id, phase}. Defensive; never throws.
+function writeRequirementNode(db, params) {
+  if (!isPlainObject(params)) {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const { reqId, phase } = params;
+  if (typeof reqId !== 'string' || reqId.length === 0) {
+    return { ok: false, reason: 'invalid_req_id' };
+  }
+  if (typeof phase !== 'string' || phase.length === 0) {
+    return { ok: false, reason: 'invalid_phase' };
+  }
+  const props = { req_id: reqId, phase: phase };
+  let propsJson;
+  try {
+    propsJson = JSON.stringify(props);
+  } catch (_e) {
+    return { ok: false, reason: 'properties_serialize_failed' };
+  }
+  const nodeId = REQUIREMENT_NODE_ID(reqId);
+  const sourcePath = 'requirement:' + phase + ':' + reqId;
+  try {
+    insertNode(db, nodeId, 'requirement', propsJson, {
+      source_path: sourcePath,
+      created_by: 'system',
+      confidence: 1.0,
+      review_status: 'confirmed',
+      // R17-02 (Task 4 Decision 4): 'observation' -- system bookkeeping.
+      epistemic_type: 'observation',
+    });
+  } catch (e) {
+    return { ok: false, reason: 'requirement_write_failed', detail: String(e.message || '').slice(0, 80) };
+  }
+  return { ok: true, node_id: nodeId };
+}
+
+// writeLineageEdge(db, {source_id, target_id, edge_type, properties}) -- a thin
+// pass-through to edges.writeEdge that FIRST constrains edge_type to the LINEAGE
+// subset {FEEDS_INTO, VALIDATES, INFORMS}. The constraint means:
+//   - a non-taxonomy type (BOGUS_LINK) is rejected here (and would also be
+//     rejected by writeEdge);
+//   - a real-but-non-lineage type (DEFERRED) is rejected HERE even though
+//     writeEdge would accept it -- the lineage writer does not widen the
+//     taxonomy, it narrows the accepted set.
+// edges.writeEdge stays the single source of truth for the predicate vocabulary
+// (its ALLOWED_EDGE_TYPES gate); this writer never adds a new member.
+// Defensive; never throws on caller input.
+function writeLineageEdge(db, params) {
+  if (!isPlainObject(params)) {
+    return { ok: false, reason: 'invalid_params' };
+  }
+  const { edge_type } = params;
+  if (typeof edge_type !== 'string' || !LINEAGE_EDGE_TYPE_SET.has(edge_type)) {
+    return { ok: false, reason: 'invalid_lineage_edge_type', detail: String(edge_type).slice(0, 40) };
+  }
+  return edges.writeEdge(db, params);
+}
+
+module.exports = {
+  ARTIFACT_TYPES,
+  ARTIFACT_TYPE_SET,
+  LINEAGE_EDGE_TYPES,
+  ARTIFACT_NODE_ID,
+  REQUIREMENT_NODE_ID,
+  writePlanningArtifactNode,
+  writeRequirementNode,
+  writeLineageEdge,
+};

package/lib/core/navigation/projections.cjs

@@ -0,0 +1,295 @@
+'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;
+}
+
+// Phase 150-04 (MEM-07): the brainAnchors PRODUCER -- closes the orphaned
+// consumer at resolveActiveFrameworks (the weight-0.5 brain_md signal at :108
+// consumed roomState.brainAnchors but nothing populated it).
+//
+// deriveBrainAnchors(cortexNodes) reads the projected BRAIN-derivation cortex
+// node (the BRAIN-kind memory_artifact surfaced by getRoomContext legD, Phase
+// 150-04 Task 2) and returns the generic framework-name handles Phase 90 derives
+// (the BRAIN node's properties.anchors array). Part 8: only generic framework-name
+// handles flow -- never BRAIN.md prose (threat T-150-04-03). Defensive: returns []
+// on any malformed/absent input; never throws.
+//
+// CHOSEN PRODUCER SITE: projections.cjs (this module), NOT the getRoomContext->
+// roomState adapter. Rationale: resolveActiveFrameworks lives here and consumes
+// roomState.brainAnchors here, so co-locating the producer keeps the brain_md
+// signal's producer + consumer in one auditable module; the caller assembles
+// roomState.brainAnchors = deriveBrainAnchors(roomContext.cortexNodes) before
+// calling resolveActiveFrameworks. resolveActiveFrameworks stays the PURE consumer.
+function deriveBrainAnchors(cortexNodes) {
+  if (!Array.isArray(cortexNodes) || cortexNodes.length === 0) return [];
+  const out = [];
+  const seen = new Set();
+  for (const n of cortexNodes) {
+    if (!n || typeof n !== 'object' || n.type !== 'memory_artifact') continue;
+    const props = (n.properties && typeof n.properties === 'object') ? n.properties : {};
+    if (props.kind !== 'BRAIN') continue;
+    const anchors = Array.isArray(props.anchors) ? props.anchors : [];
+    for (const a of anchors) {
+      // Generic framework-name handles only -- a string, no prose. Part 8.
+      if (typeof a === 'string' && a.length > 0 && !seen.has(a)) {
+        seen.add(a);
+        out.push(a);
+      }
+    }
+  }
+  return out;
+}
+
+// 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 (Phase 177 BCH-S1: + runtime turn_count term).
+//   base  = framework_invocations / 10        (D3, Phase 125 -- the original term)
+//   turn  = turn_count / TURN_DIVISOR          (Phase 177 -- the NEW per-turn runtime term)
+//   level = min(1.0, max(0.0, base + turn))    (ADDITIVE; clamped to [0,1])
+//   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; floors at 0.0 for missing or negative counters. 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)
+//
+// Phase 177 BCH-S1 (D-177-Q5): investment_level is THE single canonical runtime
+// number. This extends it to fold in a NEW runtime turn_count term ADDITIVELY on
+// top of the existing framework_invocations term. The function stays PURE (same
+// inputs -> same output, no I/O). When roomState.turn_count is absent or non-number
+// the turn term contributes 0, so every framework_invocations-only caller (and the
+// test-f-selector-ranker + navigation-projections suites) stays byte-stable.
+//
+//   turn_count: the per-turn runtime counter (a number; absent / non-number / negative
+//     contributes 0, mirroring the framework_invocations defensive read above). TURN_DIVISOR
+//     is 20 so a deep multi-turn conversation ramps the gradient gently relative to the
+//     framework term (10 framework invocations or 20 turns each reach full local on their own).
+//
+//   Reserved jump-condition fields (read-if-present, default no-op; the deterministic jumps
+//   -- escape hatch / saturation / pushback / evidence -- are folded in by LATER WAVES; named
+//   here so the canonical number has one documented home and absent fields never alter the
+//   result): roomState.investment_jump_escape_hatch, .investment_jump_saturation,
+//   .investment_jump_pushback, .investment_jump_evidence -- each, when a finite number, adds
+//   ADDITIVELY before the clamp; absent / non-number contributes 0. Wave 1 ships the read-if-
+//   present plumbing only; no caller sets them yet, so behavior is unchanged today.
+//
+// The prose Ask-Tell dial is INJECTED from this number in Pass 2 (a later wave), NOT computed
+// by the model (D-177-Q5). This function adds NO prompt-side dial computation.
+const TURN_DIVISOR = 20;
+
+function _finiteNonNegative(v) {
+  return (typeof v === 'number' && Number.isFinite(v)) ? Math.max(0, v) : 0;
+}
+
+function _jumpTerm(roomState, key) {
+  // Read-if-present reserved jump condition. Absent / non-number -> 0 (no-op).
+  // Negative jumps are NOT floored to 0 here (a future wave may model a pull-back),
+  // but the final level is clamped to [0,1], so a negative jump can only pull the
+  // gradient down, never below 0.
+  if (!roomState || typeof roomState !== 'object') return 0;
+  const v = roomState[key];
+  return (typeof v === 'number' && Number.isFinite(v)) ? v : 0;
+}
+
+function computeInvestmentLevel(roomState) {
+  const rawFw =
+    roomState && typeof roomState === 'object' && typeof roomState.framework_invocations === 'number'
+      ? roomState.framework_invocations
+      : 0;
+  const baseTerm = Math.max(0.0, rawFw) / 10;
+  // NEW runtime turn_count term (BCH-S1). Absent / non-number / negative -> 0.
+  const turnTerm = _finiteNonNegative(
+    roomState && typeof roomState === 'object' ? roomState.turn_count : undefined
+  ) / TURN_DIVISOR;
+  // Reserved jump conditions (read-if-present; default no-op until a later wave sets them).
+  const jumpTerm =
+      _jumpTerm(roomState, 'investment_jump_escape_hatch')
+    + _jumpTerm(roomState, 'investment_jump_saturation')
+    + _jumpTerm(roomState, 'investment_jump_pushback')
+    + _jumpTerm(roomState, 'investment_jump_evidence');
+  const level = Math.min(1.0, Math.max(0.0, baseTerm + turnTerm + jumpTerm));
+  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,
+  // Phase 150-04 (MEM-07): the brainAnchors producer (closes the orphaned
+  // weight-0.5 brain_md consumer). Callers assemble
+  //   roomState.brainAnchors = deriveBrainAnchors(roomContext.cortexNodes)
+  // before resolveActiveFrameworks. Generic framework-name handles only (Part 8).
+  deriveBrainAnchors,
+  // Test seam (private; used by lib/memory/navigation-projections.test.cjs only).
+  _test: { _extractFrameworkFromThought, _jtbdToFramework, KNOWN_FRAMEWORK_HINTS },
+};

package/lib/core/navigation/ranker-weights.cjs

@@ -0,0 +1,133 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 222-01 typed accessor pair over the ranker_weights table (D-02).
+ * ======================================================================
+ * This module and the migration (lib/core/migrations/phase-222-ranker-weights.cjs)
+ * are the ONLY two places SQL touches the ranker_weights table (Canon Part 9
+ * single-chokepoint invariant). navigation.cjs re-exports readWeightState /
+ * upsertWeightState as readHedgeWeightState / upsertHedgeWeightState so every
+ * caller reaches the table through the one governed door, never a bare
+ * db.prepare escape hatch.
+ *
+ * Read side DISCLOSES, write side VALIDATES:
+ *   - readWeightState returns values AS STORED (no clamping, no laundering) so a
+ *     corrupt row is VISIBLE to the ranker (Plan 02), which decides whether to
+ *     emit the Req 7 reach_weight_state_unavailable degrade event. Zero rows
+ *     (cold start) returns null, never a throw and never an event. A missing or
+ *     unreadable table THROWS (SQL errors propagate) so the ranker can disclose
+ *     the fault.
+ *   - upsertWeightState rejects non-finite / negative / non-object weights at the
+ *     write boundary (TypeError) -- WR-02: the SAME definition of "corrupt" the
+ *     read side already applies (readHedgeWeights treats v < 0 as corrupt), so a
+ *     negative weight can never be written here only to surface as a confusing
+ *     corrupt_scalar degrade event on a LATER read. It also wraps all row
+ *     upserts in ONE transaction (D-02
+ *     atomic-write discipline), mirroring the migration's own BEGIN/COMMIT/ROLLBACK
+ *     -- BUT ONLY WHEN IT OWNS THE TRANSACTION BOUNDARY. node:sqlite's
+ *     DatabaseSync has no nested-transaction support: a bare `db.exec('BEGIN')`
+ *     against a handle that is ALREADY mid-transaction throws, and an
+ *     unconditional catch-side ROLLBACK would then discard the CALLER's entire
+ *     pending transaction, not just this module's own failed insert (CR-01,
+ *     reproduced against real node:sqlite -- an outer INSERT survives a failed
+ *     nested BEGIN right up until the unconditional ROLLBACK wipes it). Fixed by
+ *     checking `db.isTransaction` (a real, documented node:sqlite DatabaseSync
+ *     property) before issuing BEGIN/COMMIT/ROLLBACK: when a transaction is
+ *     already open, this function performs its upsert AS PART OF the caller's
+ *     transaction and never issues BEGIN, COMMIT, or ROLLBACK itself -- the
+ *     caller who opened the transaction owns its commit/rollback fate, exactly
+ *     as SQL semantics require. This module only ever wraps its own BEGIN/COMMIT
+ *     when it is the one opening the transaction.
+ *
+ * This module never opens its own db; it operates only on the caller-passed
+ * handle (which the navigation chokepoint owns).
+ *
+ * NO em-dashes anywhere in this file (CLAUDE.md HARD RULE).
+ */
+
+function readWeightState(db) {
+  // SQL errors (missing/unreadable table) PROPAGATE by design so the ranker can
+  // emit the Req 7 degrade event; only the zero-rows case returns null.
+  const rows = db.prepare(
+    'SELECT expert_id, weight, update_count, updated_at FROM ranker_weights'
+  ).all();
+  if (!rows || rows.length === 0) {
+    return null; // cold start: table exists, zero rows. NO event (Pitfall 5).
+  }
+  const weights = {};
+  let updateCount = 0;
+  let updatedAt = 0;
+  for (const r of rows) {
+    weights[r.expert_id] = r.weight; // AS STORED, no validation or clamping
+    if (typeof r.update_count === 'number' && r.update_count > updateCount) {
+      updateCount = r.update_count;
+    }
+    if (typeof r.updated_at === 'number' && r.updated_at > updatedAt) {
+      updatedAt = r.updated_at;
+    }
+  }
+  return { weights, updateCount, updatedAt };
+}
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function upsertWeightState(db, weights, opts) {
+  if (!isPlainObject(weights)) {
+    throw new TypeError('upsertWeightState: weights must be a non-empty object of finite numbers');
+  }
+  const expertIds = Object.keys(weights);
+  if (expertIds.length === 0) {
+    throw new TypeError('upsertWeightState: weights must be a non-empty object of finite numbers');
+  }
+  for (const id of expertIds) {
+    const w = weights[id];
+    // WR-02: reject negative weights at the write boundary too. The read side
+    // (readHedgeWeights in reach-hedge-ranker.cjs) already treats `v < 0` as a
+    // corrupt scalar worth a degrade event -- write-side validation must match
+    // that same definition of "corrupt," or a negative weight silently written
+    // here surfaces as a confusing corrupt_scalar degrade event on the NEXT
+    // read instead of being rejected at the point of the actual mistake.
+    if (typeof w !== 'number' || !Number.isFinite(w) || w < 0) {
+      throw new TypeError('upsertWeightState: weight for ' + id + ' must be a finite, non-negative number; got ' + String(w));
+    }
+  }
+  const options = isPlainObject(opts) ? opts : {};
+  const updateCount = Number.isInteger(options.updateCount) ? options.updateCount : 0;
+  const updatedAt = typeof options.updatedAt === 'number' && Number.isFinite(options.updatedAt)
+    ? options.updatedAt
+    : Date.now();
+
+  // CR-01: node:sqlite's DatabaseSync has no nested-transaction support. A
+  // caller-threaded handle (e.g. a caller that opened its own handle and began
+  // a transaction before invoking the Hedge refit) may already be
+  // mid-transaction when this fires.
+  // db.isTransaction (a real DatabaseSync property, verified against the shipped
+  // node:sqlite) discloses that state, so this function only opens/closes ITS OWN
+  // transaction when none is already open. When one IS already open, the upsert
+  // runs as part of the caller's transaction and this function issues no BEGIN,
+  // COMMIT, or ROLLBACK of its own -- the caller who opened the transaction is the
+  // only one who may commit or roll it back. This is what stops an unconditional
+  // ROLLBACK here from silently discarding a caller's unrelated pending writes.
+  const ownsTransaction = db.isTransaction !== true;
+  if (ownsTransaction) db.exec('BEGIN');
+  try {
+    const stmt = db.prepare(
+      'INSERT INTO ranker_weights (expert_id, weight, update_count, updated_at) VALUES (?, ?, ?, ?) ' +
+      'ON CONFLICT(expert_id) DO UPDATE SET weight=excluded.weight, ' +
+      'update_count=excluded.update_count, updated_at=excluded.updated_at'
+    );
+    for (const id of expertIds) {
+      stmt.run(id, weights[id], updateCount, updatedAt);
+    }
+    if (ownsTransaction) db.exec('COMMIT');
+  } catch (err) {
+    if (ownsTransaction) db.exec('ROLLBACK');
+    throw err;
+  }
+  return { applied: true, count: expertIds.length };
+}
+
+module.exports = { readWeightState, upsertWeightState };