@mindrian_os/install 1.13.0-beta.11

package/lib/core/navigation/packet.cjs

@@ -0,0 +1,182 @@
+'use strict';
+// Phase 109-07 Brain Packet Builder. Per CONTEXT D-06 + RESEARCH section 7.
+// Phase 109 ships the BUILDER; Phase 110 ships the schema validator + brainClient.query call.
+//
+// Canon Part 8 LOAD-BEARING: zero raw room content egress. The packet payload carries ONLY
+// generic framework handles, phase identifiers, sha256 hashes, and enum scalars. ZERO
+// user-content strings, ZERO artifact bodies, ZERO meeting transcripts. Every field is
+// projected through a safe-shape mapper that strips body/properties/transcript fields.
+// Canon Part 9: builder produces the JS object; Phase 110 wraps with validateAndSendBrainPacket;
+// Phase 109 honors the privacy: 'no_raw_artifact_text' field by default in constraints.
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { getNeighborhood } = require('./neighborhood.cjs');
+const { findContradictions, findUnsupportedClaims, findRelevantOpportunities } = require('./insights.cjs');
+const { findRecentChanges } = require('./memory-events.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 loadOperator(roomDir, mocks) {
+  if (mocks && mocks.operator) return mocks.operator;
+  try { return require(path.resolve(__dirname, '..', '..', 'conversation', 'operator.cjs')); } catch (_) { return null; }
+}
+
+function shortText(propertiesOrJson) {
+  let p = propertiesOrJson;
+  if (typeof p === 'string') {
+    try { p = JSON.parse(p); } catch (_) { p = {}; }
+  }
+  p = p || {};
+  const candidates = [p.summary, p.claim, p.title, p.text];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.length > 0) {
+      return c.length > 120 ? c.slice(0, 117) + '...' : c;
+    }
+  }
+  return '';
+}
+
+function safeNodeProjection(db, n) {
+  // Project only safe scalar fields. Re-fetch properties to compute summary; never include body.
+  const row = db.prepare('SELECT properties FROM nodes WHERE id = ?').get(n.id);
+  const summary = row ? shortText(row.properties) : '';
+  return {
+    id: n.id,
+    type: n.type,
+    summary,
+    depth: n.depth,
+    edgeTypeIn: n.edgeTypeIn,
+    score: typeof n.score === 'number' ? Math.round(n.score * 1000) / 1000 : 0,
+    reviewStatus: n.reviewStatus,
+    lastSeenAt: n.lastSeenAt,
+  };
+}
+
+function safeContradictionProjection(c) {
+  return {
+    claimAId: c.claimA && c.claimA.id ? c.claimA.id : null,
+    claimBId: c.claimB && c.claimB.id ? c.claimB.id : null,
+    depth: 1,
+    explanation: c.explanation,
+  };
+}
+
+function safeUnsupportedProjection(u) {
+  return {
+    claimId: u.claim && u.claim.id ? u.claim.id : null,
+    type: u.claim && u.claim.type ? u.claim.type : null,
+    reviewStatus: u.claim && u.claim.reviewStatus ? u.claim.reviewStatus : null,
+    lastSeenAt: u.claim && u.claim.lastSeenAt ? u.claim.lastSeenAt : null,
+    explanation: u.explanation,
+  };
+}
+
+function safeRecentChangeProjection(r) {
+  return {
+    id: r.id,
+    eventType: r.eventType,
+    targetNodeId: r.targetNodeId,
+    createdAt: r.createdAt,
+  };
+}
+
+function hsiBand(score) {
+  const s = Number(score) || 0;
+  if (s >= 70) return 'high';
+  if (s >= 40) return 'medium';
+  return 'low';
+}
+
+function surface_banked_opportunities(db, focusNodeId, mocks) {
+  const opps = findRelevantOpportunities(db, focusNodeId, { topK: 3, _mocks: mocks });
+  return {
+    count: opps.length,
+    items: opps.map((o) => ({
+      id_hash: crypto.createHash('sha256').update(String(o.opportunityId || '')).digest('hex').slice(0, 12),
+      tags: Array.isArray(o.tags) ? o.tags.filter((t) => typeof t === 'string' && t.length <= 30) : [],
+      hsi_band: hsiBand(o.hsiScore),
+      composite_score: Math.round((Number(o.compositeScore) || 0) * 100) / 100,
+    })),
+  };
+}
+
+function getRoomStage(db) {
+  try {
+    const row = db.prepare("SELECT value FROM identity WHERE key = 'stage'").get();
+    if (row && typeof row.value === 'string' && row.value.length > 0) return row.value;
+  } catch (_) { /* ignore */ }
+  return 'unknown';
+}
+
+function getFocusType(db, focusNodeId) {
+  const row = db.prepare('SELECT type FROM nodes WHERE id = ?').get(focusNodeId);
+  return row ? row.type : null;
+}
+
+function buildBrainPacket(db, job, focusNodeId, opts) {
+  const options = opts || {};
+  const mocks = options._mocks;
+  const roomId = options.roomId || null;
+
+  // Active context. Mocks override the require() calls for hermetic tests.
+  const jtbdMod = loadJtbd(null, mocks);
+  const opMod = loadOperator(null, mocks);
+  const jtbdRaw = jtbdMod ? jtbdMod.getCurrent(null) : null;
+  const opRaw = opMod ? opMod.getCurrent(null) : null;
+  const jtbdId = jtbdRaw && jtbdRaw.current && jtbdRaw.current.id ? jtbdRaw.current.id : null;
+  const operator = opRaw && opRaw.current ? opRaw.current : 'JUST_TALK';
+
+  // Focus node.
+  const focusType = getFocusType(db, focusNodeId);
+  const focusRow = db.prepare('SELECT properties FROM nodes WHERE id = ?').get(focusNodeId);
+  const focusSummary = focusRow ? shortText(focusRow.properties) : '';
+
+  // Local graph summary. Each helper output passes through a safe-shape mapper so
+  // raw bodies, transcripts, and absolute paths NEVER reach the packet payload.
+  const neighborhood = getNeighborhood(db, focusNodeId, { maxDepth: 2, topK: 50 });
+  const nearestClaims = neighborhood
+    .filter((n) => ['claim', 'CausalClaim'].includes(n.type))
+    .slice(0, 5)
+    .map((n) => safeNodeProjection(db, n));
+  const nearestAssumptions = neighborhood
+    .filter((n) => n.type === 'assumption')
+    .slice(0, 5)
+    .map((n) => safeNodeProjection(db, n));
+  const contradictions = findContradictions(db, focusNodeId).slice(0, 5).map(safeContradictionProjection);
+  const unsupportedClaims = findUnsupportedClaims(db, roomId || 'unknown').slice(0, 5).map(safeUnsupportedProjection);
+  const recentChanges = findRecentChanges(db, Date.now() - 24 * 60 * 60 * 1000, { limit: 10 }).map(safeRecentChangeProjection);
+  const bankedOpportunities = surface_banked_opportunities(db, focusNodeId, mocks);
+
+  return {
+    packet_version: '1.0',
+    job,
+    room_stage: getRoomStage(db),
+    active_context: {
+      jtbd: jtbdId,
+      operator,
+      focus_node: {
+        id: focusNodeId,
+        type: focusType,
+        summary: focusSummary,
+      },
+    },
+    local_graph_summary: {
+      nearest_claims: nearestClaims,
+      nearest_assumptions: nearestAssumptions,
+      contradictions,
+      unsupported_claims: unsupportedClaims,
+      recent_changes: recentChanges,
+      banked_opportunities: bankedOpportunities,
+    },
+    constraints: {
+      privacy: 'no_raw_artifact_text',
+      max_tokens: 1200,
+    },
+  };
+}
+
+module.exports = { buildBrainPacket, surface_banked_opportunities, shortText };

package/lib/core/navigation/room-home.cjs

@@ -0,0 +1,127 @@
+'use strict';
+// Phase 109-09 Room Home Driver. Per CONTEXT D-08 + RESEARCH section 6.
+// Composition NOT duplication. ZERO new SQL queries; 8 reads via existing helpers + 3 raw SELECTs.
+//
+// Canon Part 1: getRoomHomeView IS the wicked navigator's working memory made legible.
+// Canon Part 4: every payload is composed from typed graph queries; the navigator never
+// re-derives; the same node id never appears twice across confirmedFacts and riskyAssumptions
+// (composition-not-duplication invariant asserted in tests/test-room-home-vs-brain-derivation-regression.cjs).
+// Canon Part 7: composes Plan 109-04 getNeighborhood + Plan 109-05 findContradictions /
+// findOpenQuestions / findRelevantOpportunities + Plan 109-03 findRecentChanges; ZERO
+// new SQL queries beyond the 3 thin raw SELECTs that scope confirmed-facts / risky-assumptions /
+// evidence-by-tier (each a single SELECT against nodes; cheaper than a CTE for small N).
+// Canon Part 9: SELECT supersedes folder scanning; this is the user-facing payoff of Phase 109.
+
+const { findContradictions, findOpenQuestions, findRelevantOpportunities } = require('./insights.cjs');
+const { findRecentChanges } = require('./memory-events.cjs');
+
+const TIERS = ['academic', 'operational', 'practitioner', 'none'];
+
+function getCurrentThesis(db) {
+  try {
+    const row = db.prepare("SELECT value FROM identity WHERE key = 'thesis'").get();
+    return row && typeof row.value === 'string' ? row.value : '';
+  } catch (_) {
+    return '';
+  }
+}
+
+function safeShape(row) {
+  let summary = '';
+  try {
+    const props = JSON.parse(row.properties || '{}');
+    summary = props.summary || props.claim || props.title || '';
+  } catch (_) { /* ignore */ }
+  return {
+    id: row.id,
+    type: row.type,
+    summary: summary.length > 120 ? summary.slice(0, 117) + '...' : summary,
+    reviewStatus: row.review_status,
+    confidence: row.confidence,
+    lastSeenAt: row.last_seen_at,
+  };
+}
+
+function getConfirmedFacts(db) {
+  // Per CONTEXT D-08 + Plan 108 TRUTH-STATES: validated state is the strict
+  // confirmed-fact tier (claim / CausalClaim / assumption that cleared review).
+  const rows = db.prepare(
+    "SELECT id, type, properties, review_status, confidence, last_seen_at FROM nodes "
+    + "WHERE type IN ('claim','CausalClaim','assumption') AND review_status = 'validated' "
+    + "ORDER BY last_seen_at DESC LIMIT 50"
+  ).all();
+  return rows.map(safeShape);
+}
+
+function getRiskyAssumptions(db) {
+  // Per CONTEXT D-08: risky = assumption nodes still in active review_status
+  // (confirmed = filed but not yet validated; needs_evidence = explicitly flagged).
+  // Composition-not-duplication: this set is disjoint from confirmedFacts because the
+  // 'validated' state is excluded by the IN-clause filter.
+  const rows = db.prepare(
+    "SELECT id, type, properties, review_status, confidence, last_seen_at FROM nodes "
+    + "WHERE type = 'assumption' AND review_status IN ('confirmed','needs_evidence') "
+    + "ORDER BY confidence ASC, last_seen_at DESC LIMIT 50"
+  ).all();
+  return rows.map(safeShape);
+}
+
+function getEvidenceByTier(db) {
+  // Per CONTEXT D-08 evidence shape: { academic, operational, practitioner, none }
+  // grouped from evidence nodes by properties.tier. JS-side grouping is cheaper than
+  // GROUP BY for typical evidence counts (< 200) and preserves ordering by confidence.
+  const rows = db.prepare(
+    "SELECT id, type, properties, review_status, confidence, last_seen_at, "
+    + "json_extract(properties, '$.tier') AS tier "
+    + "FROM nodes WHERE type = 'evidence' "
+    + "ORDER BY confidence DESC LIMIT 200"
+  ).all();
+  const out = { academic: [], operational: [], practitioner: [], none: [] };
+  for (const r of rows) {
+    const tier = TIERS.includes(r.tier) ? r.tier : 'none';
+    out[tier].push(safeShape(r));
+  }
+  return out;
+}
+
+function getRoomHomeView(db, roomId, opts) {
+  const options = opts || {};
+  const roomRootId = 'room:' + roomId;
+  const since24h = Date.now() - 24 * 60 * 60 * 1000;
+
+  // 8 reads total: 1 identity + 3 raw SELECTs + 4 helper calls.
+  const currentThesis = getCurrentThesis(db);
+  const confirmedFacts = getConfirmedFacts(db);
+  const riskyAssumptions = getRiskyAssumptions(db);
+  const evidence = getEvidenceByTier(db);
+  const contradictions = findContradictions(db, roomRootId);
+  const openQuestions = findOpenQuestions(db, roomId);
+  const recentChanges = findRecentChanges(db, since24h, { limit: 20 });
+  const bankedOpportunities = findRelevantOpportunities(
+    db,
+    roomRootId,
+    { topK: 5, _mocks: options._mocks, roomDir: options.roomDir }
+  );
+
+  // Per RESEARCH section 6.1 line 882: nextMove ships a templated default in Phase 109;
+  // Phase 110 wires the live Brain advisory. The opts.brainAvailable + opts.getBrainAdvisory
+  // seam is forward-compat; until Phase 110 is shipped, the templated string is the
+  // canonical answer.
+  const nextMove = options.brainAvailable === true && typeof options.getBrainAdvisory === 'function'
+    ? options.getBrainAdvisory(roomRootId)
+    : 'See open questions and contradictions to decide next focus.';
+
+  return {
+    currentThesis,
+    confirmedFacts,
+    riskyAssumptions,
+    evidence,
+    contradictions,
+    openQuestions,
+    recentChanges,
+    bankedOpportunities,
+    nextMove,
+  };
+}
+
+module.exports = { getRoomHomeView };

package/lib/core/navigation/transitions.cjs

@@ -0,0 +1,82 @@
+'use strict';
+// Phase 109-04 truth-state transition chokepoint. Per Phase 108 TRUTH-STATES.md L40-58
+// and L88. Every promoteNodeStatus call validates the transition pair against the
+// closed Set; logs a status_* memory_event; populates confirmed_by + confirmed_at when
+// transitioning to confirmed or validated.
+//
+// Canon Part 4: every status change is graph data; the memory_event row IS the audit
+// edge for the transition.
+// Canon Part 9: truth-state promotion is gated by the documented 8-transition closed
+// taxonomy; any other (from, to) pair is rejected.
+
+const { logEvent } = require('./memory-events.cjs');
+
+// Closed Set of allowed (from, to) transitions. The Set member is 'from->to' string.
+const TRANSITIONS = Object.freeze(new Set([
+  'proposed->confirmed',
+  'proposed->needs_evidence',
+  'needs_evidence->validated',
+  'confirmed->validated',
+  'validated->invalidated',
+  'proposed->rejected',
+  'confirmed->superseded',
+  'confirmed->stale',
+]));
+
+// event_type for each transition.
+const EVENT_FOR_TRANSITION = Object.freeze({
+  'proposed->confirmed': 'status_promoted',
+  'proposed->needs_evidence': 'status_promoted',
+  'needs_evidence->validated': 'status_promoted',
+  'confirmed->validated': 'status_promoted',
+  'validated->invalidated': 'status_promoted',
+  'proposed->rejected': 'status_rejected',
+  'confirmed->superseded': 'status_superseded',
+  'confirmed->stale': 'status_stale',
+});
+
+function promoteNodeStatus(db, nodeId, fromStatus, toStatus, byUser, reason) {
+  const key = fromStatus + '->' + toStatus;
+  if (!TRANSITIONS.has(key)) {
+    return { ok: false, reason: 'invalid_transition' };
+  }
+  const row = db.prepare('SELECT id, review_status FROM nodes WHERE id = ?').get(nodeId);
+  if (!row) {
+    return { ok: false, reason: 'unknown_node' };
+  }
+  if (row.review_status !== fromStatus) {
+    return { ok: false, reason: 'state_mismatch', currentStatus: row.review_status };
+  }
+  const setsConfirmed = (toStatus === 'confirmed' || toStatus === 'validated');
+  const nowMs = Date.now();
+  db.exec('BEGIN');
+  try {
+    if (setsConfirmed) {
+      db.prepare('UPDATE nodes SET review_status = ?, confirmed_by = ?, confirmed_at = ?, last_seen_at = ? WHERE id = ?')
+        .run(toStatus, byUser || 'system', nowMs, nowMs, nodeId);
+    } else {
+      db.prepare('UPDATE nodes SET review_status = ?, last_seen_at = ? WHERE id = ?')
+        .run(toStatus, nowMs, nodeId);
+    }
+    const eventType = EVENT_FOR_TRANSITION[key];
+    const evRes = logEvent(db, eventType, {
+      target_node_id: nodeId,
+      previous_status: fromStatus,
+      new_status: toStatus,
+      reason: typeof reason === 'string' ? reason : null,
+      created_by: byUser || 'system',
+      source_path: 'transition:' + key,
+    });
+    if (!evRes.ok) {
+      db.exec('ROLLBACK');
+      return { ok: false, reason: 'event_log_failed:' + evRes.reason };
+    }
+    db.exec('COMMIT');
+    return { ok: true, eventId: evRes.eventId };
+  } catch (err) {
+    try { db.exec('ROLLBACK'); } catch (_) { /* ignore */ }
+    return { ok: false, reason: err.message };
+  }
+}
+
+module.exports = { promoteNodeStatus, TRANSITIONS, EVENT_FOR_TRANSITION };

package/lib/core/navigation-engine-shared.cjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-00 -- Navigation Engine shared helpers (pure, zero I/O)
+ * ================================================================
+ * Frozen constants and pure helper functions that the L5 Navigation
+ * Engine (lib/core/navigation-engine.cjs) composes into a structured
+ * decision function. Splitting these out keeps the engine entry point
+ * thin and lets unit tests exercise the rules without booting a full
+ * fixture room.
+ *
+ * Contract source of truth:
+ *   .planning/research/navigation-engine-brain-interface.md (v1, frozen
+ *   at Phase 90-09).
+ *
+ * What this module exports:
+ *   STALENESS_MULTIPLIERS  frozen table -- Section 4.1 multiplier rows
+ *   CANONICAL_VERBS        frozen 10-entry array -- Canon Part 3 vocabulary
+ *   SECTION_WEIGHTS        frozen map -- Section 3.2 (required + optional)
+ *   applyStalenessMultiplier(brain) -> number in [0, 1]
+ *   resolveTierMode(quadruple, brainAvailable) -> 'mode_a' | 'mode_b' | 'tier_0'
+ *   emptyDecision()        decision shell
+ *   emptyDecisionTrace()   trace shell with all 8 Section 8 fields
+ *
+ * Canon Part 8 posture:
+ *   This module does ZERO I/O. No fs, no network, no child_process. It
+ *   only computes pure functions over already-parsed quadruple structs.
+ *   The Brain boundary is irrelevant here because no bytes leave or
+ *   enter; all guarding is delegated to the engine entry point.
+ *
+ * License: BSL 1.1.
+ */
+
+// ---------- Frozen constants ----------
+
+/**
+ * Section 4.1 staleness multiplier table.
+ * Keys are sentinel labels:
+ *   'null'                            -- brain === null (BRAIN.md absent)
+ *   'fresh'                           -- staleness === 'fresh'
+ *   'unavailable'                     -- staleness === 'unavailable'
+ *   <stale_reason string>             -- staleness === 'stale' AND
+ *                                        stale_reason === <key>
+ *
+ * Values are the multiplier applied to the BRAIN.md contribution block.
+ */
+const STALENESS_MULTIPLIERS = Object.freeze({
+  null: 0.0,
+  fresh: 1.0,
+  age_exceeded: 0.7,
+  governing_thought_changed: 0.3,
+  brain_graph_version_mismatch: 0.5,
+  brain_offline: 0.9, // EXEMPT per Section 4.2 (transient network)
+  derivation_timeout: 0.2,
+  parse_failed: 0.0,
+  unavailable: 0.0,
+});
+
+/**
+ * Canon Part 3 canonical 10-verb vocabulary. Closed set; new verbs
+ * require a canon amendment, not a runtime addition.
+ */
+const CANONICAL_VERBS = Object.freeze([
+  'Run Methodology',
+  'Reformulate',
+  'Spawn Sub-Agent',
+  'Navigate Graph',
+  "Devil's Advocate",
+  'Scenario Plan',
+  'Synthesize',
+  'Bank Opportunity',
+  'Defer',
+  'Free-Text',
+]);
+
+/**
+ * Section 3.2 weights. Required sections sum to exactly 1.0:
+ *   0.35 + 0.20 + 0.15 + 0.10 + 0.10 + 0.05 + 0.05 = 1.00
+ *
+ * Optional sections (flagged_contradictions_xroom, hsi_signals) carry
+ * weight 0 and are surfaced as decision_trace caveats only.
+ */
+const SECTION_WEIGHTS = Object.freeze({
+  // Required (sum to 1.0):
+  pattern_matches: 0.35,
+  framework_chain_predictions: 0.20,
+  cross_domain_analogies: 0.15,
+  wicked_indicators: 0.10,
+  unfilled_opportunity_matches: 0.10,
+  assessment_thinking_chain_position: 0.05,
+  problemtype_classification: 0.05,
+  // Optional (caveat only):
+  flagged_contradictions_xroom: 0,
+  hsi_signals: 0,
+});
+
+const REQUIRED_SECTION_KEYS = Object.freeze([
+  'pattern_matches',
+  'framework_chain_predictions',
+  'cross_domain_analogies',
+  'wicked_indicators',
+  'unfilled_opportunity_matches',
+  'assessment_thinking_chain_position',
+  'problemtype_classification',
+]);
+
+const OPTIONAL_SECTION_KEYS = Object.freeze([
+  'flagged_contradictions_xroom',
+  'hsi_signals',
+]);
+
+// ---------- Pure helpers ----------
+
+/**
+ * applyStalenessMultiplier(brain) -> number in [0, 1]
+ *
+ * Resolves the BRAIN.md staleness multiplier per Section 4.1. Never
+ * throws; falls back to 0.0 conservatively on any unrecognized shape.
+ *
+ * Decision order (highest precedence first):
+ *   1. brain === null                         -> 0.0
+ *   2. brain.parse_failed === true            -> 0.0  (override)
+ *   3. brain.staleness === 'unavailable'      -> 0.0
+ *   4. brain.staleness === 'fresh'            -> 1.0
+ *   5. brain.staleness === 'stale' + known reason -> table lookup
+ *   6. unknown shape                          -> 0.0  (conservative)
+ */
+function applyStalenessMultiplier(brain) {
+  if (brain === null || brain === undefined) {
+    return STALENESS_MULTIPLIERS.null;
+  }
+  if (typeof brain !== 'object') {
+    return 0.0;
+  }
+  if (brain.parse_failed === true) {
+    return STALENESS_MULTIPLIERS.parse_failed;
+  }
+  const staleness = brain.staleness;
+  if (staleness === 'unavailable') {
+    return STALENESS_MULTIPLIERS.unavailable;
+  }
+  if (staleness === 'fresh') {
+    return STALENESS_MULTIPLIERS.fresh;
+  }
+  if (staleness === 'stale') {
+    const reason = brain.stale_reason;
+    if (typeof reason === 'string' && Object.prototype.hasOwnProperty.call(STALENESS_MULTIPLIERS, reason)) {
+      const m = STALENESS_MULTIPLIERS[reason];
+      // Clamp [0, 1] defensively even though all table values are in range.
+      if (typeof m === 'number' && m >= 0.0 && m <= 1.0) return m;
+      return 0.0;
+    }
+    // Unknown stale_reason -- fall through to conservative zero.
+    return 0.0;
+  }
+  // Unknown staleness label -- conservative zero.
+  return 0.0;
+}
+
+/**
+ * resolveTierMode(quadruple, brainAvailable) -> 'mode_a' | 'mode_b' | 'tier_0'
+ *
+ * Implements Section 5 logic exactly. Re-evaluated every turn (no
+ * cross-turn caching per Section 5.4).
+ *
+ * Mode A : brain reachable AND brain non-null AND staleness !== 'unavailable'
+ *          AND parse_failed !== true
+ * Mode B : brain unreachable AND brain non-null AND
+ *          stale_reason === 'brain_offline' (acceptable transient)
+ * Tier 0 : brain === null OR parse_failed === true OR
+ *          staleness === 'unavailable' OR (any other unreachable shape)
+ */
+function resolveTierMode(quadruple, brainAvailable) {
+  const brain = quadruple && quadruple.brain;
+  if (brain === null || brain === undefined) return 'tier_0';
+  if (brain.parse_failed === true) return 'tier_0';
+  if (brain.staleness === 'unavailable') return 'tier_0';
+  if (brainAvailable === true) {
+    return 'mode_a';
+  }
+  // Brain unreachable: only mode_b when offline-exempt. Otherwise tier_0.
+  if (brain.stale_reason === 'brain_offline') return 'mode_b';
+  return 'tier_0';
+}
+
+/**
+ * emptyDecisionTrace() -> shell with all 8 Section 8 fields + 5
+ * structural fields. Sentinel values:
+ *   scalars  -> null
+ *   booleans -> false
+ *   arrays   -> []
+ *   tier_mode -> 'tier_0' (fail-safe default)
+ */
+function emptyDecisionTrace() {
+  return {
+    // Section 8 required fields:
+    brain_md_version: null,
+    brain_md_staleness: 'absent',
+    brain_md_stale_reason: null,
+    brain_md_weight_applied: 0.0,
+    brain_md_recommended_confidence: null,
+    brain_md_recommended_marker_rendered: false,
+    brain_md_tier_mode: 'tier_0',
+    brain_md_sections_consumed: [],
+    // Structural fields (5):
+    icm_scope: null,
+    sql_signals: null,
+    minto_reasoning: null,
+    intent_persona: null,
+    chosen_rationale: null,
+  };
+}
+
+/**
+ * emptyDecision() -> empty decision shell with full empty trace.
+ */
+function emptyDecision() {
+  return {
+    fire_skill: null,
+    offer_next_step: null,
+    suppress_skills: [],
+    persona_updates: null,
+    decision_trace: emptyDecisionTrace(),
+  };
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  STALENESS_MULTIPLIERS: STALENESS_MULTIPLIERS,
+  CANONICAL_VERBS: CANONICAL_VERBS,
+  SECTION_WEIGHTS: SECTION_WEIGHTS,
+  REQUIRED_SECTION_KEYS: REQUIRED_SECTION_KEYS,
+  OPTIONAL_SECTION_KEYS: OPTIONAL_SECTION_KEYS,
+  applyStalenessMultiplier: applyStalenessMultiplier,
+  resolveTierMode: resolveTierMode,
+  emptyDecision: emptyDecision,
+  emptyDecisionTrace: emptyDecisionTrace,
+};