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

package/lib/core/brain-client.cjs

@@ -1,7 +1,9 @@
 'use strict';
 
 /**
- * Brain HTTP Client — calls mindrian-brain.onrender.com
+ * Brain HTTP Client -- calls the Brain HTTP server (currently
+ * `https://mindrian-brain.onrender.com`, moving to `https://brain.mindrian.ai`;
+ * override via the MINDRIAN_BRAIN_URL env var for staging / self-hosted).
  *
  * Replaces direct MCP tool calls (mcp__neo4j-brain__*, mcp__pinecone-brain__*)
  * with a single HTTP API that handles Neo4j + Pinecone behind one key.
@@ -20,6 +22,13 @@
 
 const BRAIN_URL = process.env.MINDRIAN_BRAIN_URL || 'https://mindrian-brain.onrender.com';
 
+// Per-request hard timeout for every Brain HTTP call (init handshake + tool
+// calls). Node's global fetch() has NO default timeout, so without this a
+// slow/wedged Brain hangs the calling /mos: command indefinitely. The Render
+// service answers in ~1-2s normally; 20s is a generous-but-bounded ceiling.
+// Override via MINDRIAN_BRAIN_TIMEOUT_MS (brain-router wants ~2000 for Tier 3).
+const BRAIN_REQUEST_TIMEOUT_MS = Number(process.env.MINDRIAN_BRAIN_TIMEOUT_MS) || 20000;
+
 // Phase 87-07 (CASCADE-06): Brain session cache with 5-minute TTL.
 // Every callTool() previously re-ran the `initialize` handshake (~1 network
 // round-trip). With a long-lived MCP server this is wasted work -- sessions
@@ -40,6 +49,13 @@ const BRAIN_URL = process.env.MINDRIAN_BRAIN_URL || 'https://mindrian-brain.onre
 // users; sha256 is effectively free at these volumes and eliminates the
 // concern entirely (R-87-07-RACE).
 const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+// Phase 123 Plan-07: getApiKey() delegates to the single Brain-key resolver.
+// The legacy inline 3-path lookup (env -> CWD .env -> ~/.mindrian.env) is gone;
+// the resolver does env -> ~/.mindrian.env -> CWD .env (D-31 order) + SEC-02
+// POSIX permission check + explicit reason strings. See HARNESS-123-15.
+const { resolveBrainKey } = require('./resolve-brain-key.cjs');
 const SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes
 /** @type {Map<string, {promise: Promise<string>, expiresAt: number}>} */
 const sessionCache = new Map();
@@ -113,37 +129,45 @@ function checkFilePermissions(envPath) {
 }
 checkFilePermissions._warned = false;
 
-/**
- * Get the Brain API key from environment.
- * Checks: MINDRIAN_BRAIN_KEY, then falls back to reading .env in CWD.
- * Every .env candidate path is gated by checkFilePermissions (SEC-02).
- */
+// Phase 123 Plan-07: getApiKey() delegates to lib/core/resolve-brain-key.cjs.
+//
+// Order: MINDRIAN_BRAIN_KEY env -> ~/.mindrian.env -> CWD .env -> not-found.
+// NOTE: this REVERSES the previous CWD-first-then-~/.mindrian.env order.
+// Rationale: the global backup (~/.mindrian.env, mode 0600 per SEC-02) is more
+// trustworthy than a project's potentially-stale .env file. Cited: Phase 123
+// D-31. The resolver returns { key, source, available, reason }; we surface
+// the key (or null) here and log a non-null reason ONCE per process via
+// console.error -- SEC-02 group/world-bit rejection routes through this
+// channel, never as a silent null.
+//
+// The legacy inline 3-path lookup and the per-file checkFilePermissions gate
+// previously inlined here are gone -- the resolver owns both responsibilities
+// now. checkFilePermissions remains exported on _test for backward-compat
+// with security-trifecta.test.cjs (the helper itself still works locally;
+// it's just not called by getApiKey anymore).
+let _memoizedKey = null;
+let _memoizedAt = 0;
+let _reasonLoggedThisProcess = false;
+const _GETKEY_MEMO_MS = 60 * 1000;
 function getApiKey() {
-  if (process.env.MINDRIAN_BRAIN_KEY) {
-    return process.env.MINDRIAN_BRAIN_KEY;
+  if (_memoizedAt && (Date.now() - _memoizedAt) < _GETKEY_MEMO_MS) {
+    return _memoizedKey;
   }
-  // Try reading .env from CWD
-  try {
-    const fs = require('fs');
-    const path = require('path');
-    const envPath = path.join(process.cwd(), '.env');
-    if (fs.existsSync(envPath) && checkFilePermissions(envPath)) {
-      const content = fs.readFileSync(envPath, 'utf8');
-      const match = content.match(/MINDRIAN_BRAIN_KEY=(.+)/);
-      if (match) return match[1].trim();
-    }
-  } catch (e) {}
-  // Fallback: try reading ~/.mindrian.env (global backup)
-  try {
-    const fs = require('fs');
-    const path = require('path');
-    const globalEnvPath = path.join(require('os').homedir(), '.mindrian.env');
-    if (fs.existsSync(globalEnvPath) && checkFilePermissions(globalEnvPath)) {
-      const content = fs.readFileSync(globalEnvPath, 'utf8');
-      const match = content.match(/MINDRIAN_BRAIN_KEY=(.+)/);
-      if (match) return match[1].trim();
-    }
-  } catch (e) {}
+  const r = resolveBrainKey();
+  if (r && r.available) {
+    _memoizedKey = r.key;
+    _memoizedAt = Date.now();
+    return _memoizedKey;
+  }
+  if (r && r.reason && !_reasonLoggedThisProcess) {
+    // SEC-02 reject + not-found-with-reason both route through stderr ONCE
+    // per process -- never a silent null. The session-start status line is
+    // the user-visible surface; this is the in-process diagnostic.
+    process.stderr.write('[mindrian-os] Brain key not loaded: ' + r.reason + '\n');
+    _reasonLoggedThisProcess = true;
+  }
+  _memoizedKey = null;
+  _memoizedAt = Date.now();
   return null;
 }
 
@@ -189,6 +213,7 @@ async function _ensureSession(apiKey) {
   const promise = (async () => {
     const initRes = await fetch(`${BRAIN_URL}/mcp`, {
       method: 'POST',
+      signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
       headers: {
         'Content-Type': 'application/json',
         'Accept': 'application/json, text/event-stream',
@@ -249,6 +274,7 @@ async function callTool(toolName, args) {
     // Call the tool
     const toolRes = await fetch(`${BRAIN_URL}/mcp`, {
       method: 'POST',
+      signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
       headers: {
         'Content-Type': 'application/json',
         'Accept': 'application/json, text/event-stream',
@@ -306,7 +332,7 @@ async function callTool(toolName, args) {
  * as { cypher, params }. The Brain tool declares `params:
  * z.record(z.any()).optional()`, so a parameterized Cypher gets its
  * bindings through cleanly. `params` MUST be a generic-handles-only object
- * — framework names, phase identifiers, problem types per Canon Part 8 —
+ * -- framework names, phase identifiers, problem types per Canon Part 8 --
  * NEVER user content (artifact bodies, meeting text, personal identifiers,
  * proprietary numbers). Previously the second arg was silently dropped, so
  * callers (rs-explain-command.cjs, rs-thesis-command.cjs, rs-nl-to-query)
@@ -319,9 +345,9 @@ async function callTool(toolName, args) {
  * `JSON.stringify(records)` where `records` is a BARE ARRAY of row objects.
  * `callTool` returns that array directly (or `{ text: 'Error: ...' }` on a
  * Cypher error, or `null` when the Brain is unreachable / no API key).
- * Consumers across the codebase — brain-router.cjs, brain-derivation.cjs's
+ * Consumers across the codebase -- brain-router.cjs, brain-derivation.cjs's
  * `renderRecords`, rs-chain-feeder.cjs, rs-experts-command.cjs,
- * rs-explain-command.cjs, rs-thesis-command.cjs — all read `result.records`,
+ * rs-explain-command.cjs, rs-thesis-command.cjs -- all read `result.records`,
  * so the bare-array shape silently dropped every row. `query` therefore now
  * ALWAYS returns `{ records: [...] }` on a successful brain_query; an
  * unreachable Brain / missing key still returns `null`; a Cypher-error
@@ -329,7 +355,7 @@ async function callTool(toolName, args) {
  * unchanged so callers that inspect the failure can still see it; any other
  * unexpected shape collapses to `{ records: [] }` so callers never crash.
  * `search`, `smartSearch`, `schema`, `stats`, `write`, `callTool` are
- * deliberately untouched — only `query` is normalized.
+ * deliberately untouched -- only `query` is normalized.
  */
 async function query(cypher, params) {
   const args = { cypher: cypher };
@@ -393,11 +419,49 @@ async function smartSearch(queryText, options = {}) {
   return pineconeResult;
 }
 
+// brain_schema is near-static (the teaching graph's label/relationship/property
+// taxonomy changes ~never) and is hit by several modules. Memoize it
+// process-wide for 30 minutes.
+let _schemaCache = null;
+let _schemaCacheAt = 0;
+const SCHEMA_CACHE_TTL_MS = 30 * 60 * 1000;
+
 /**
- * Get Neo4j schema.
+ * Get the Brain Neo4j schema (node labels, relationship types, property keys).
+ * Memoized for 30 minutes (process-wide).
  */
 async function schema() {
-  return callTool('brain_schema', {});
+  if (_schemaCache && (Date.now() - _schemaCacheAt) < SCHEMA_CACHE_TTL_MS) {
+    return _schemaCache;
+  }
+  const result = await callTool('brain_schema', {});
+  if (result != null) {
+    _schemaCache = result;
+    _schemaCacheAt = Date.now();
+  }
+  return result;
+}
+
+/**
+ * Natural-language methodology question against the Brain (wraps brain_ask).
+ *
+ * brain_ask auto-routes Pinecone/Neo4j server-side and handles its own
+ * fallback -- it is the highest-level Brain entry point. Prefer it over a
+ * hand-rolled Cypher query when the caller has a natural-language methodology
+ * question. Canon Part 8: the question string carries only generic methodology
+ * language -- never user artifacts, meeting text, or personal identifiers.
+ *
+ * Returns the parsed brain_ask payload ({ question, keyword, source, count,
+ * results: [...] }) on success; a { text: 'Error: ...' } / { error: ... }
+ * passthrough on a server-side error; null when the Brain is unreachable or no
+ * API key is configured (graceful degradation -- mirrors query()).
+ *
+ * @param {string} question
+ * @returns {Promise<object|null>}
+ */
+async function ask(question) {
+  if (typeof question !== 'string' || !question.trim()) return null;
+  return callTool('brain_ask', { question: question });
 }
 
 /**
@@ -836,6 +900,339 @@ async function getFrameworkChain(persona) {
   return getTier0Chain(personaLower);
 }
 
+// ============================================================================
+// Phase 110-03: Brain Context Packet wire enforcement (Canon Part 8 + Part 9).
+// ============================================================================
+//
+// sendPacket(packet, opts) is the SOLE typed-packet wire path. It runs:
+//   (1) D-08 layer-3 origin allowlist (the belt to the schema's suspenders --
+//       a caller who bypassed ajv still gets caught here).
+//   (2) Unknown-job guard against the closed D-02 vocabulary (12 jobs).
+//   (3) ajv in-validation (reject hard: throw + log brain_packet_rejected).
+//   (4) POST tools/call name:'brain_packet' via the existing callTool transport
+//       (degrade soft when the tool is absent: { advice:null, reason:
+//       'brain_packet_tool_absent' }; on transport error: { advice:null,
+//       reason: 'brain_unreachable' }). Never throws on Brain-side problems.
+//   (5) ajv out-validation (reject hard, degrade soft: log
+//       brain_response_rejected + return { advice:null, reason:
+//       'response_schema_invalid' }). Never throws, never partial-ingests.
+//   (6) Returns the validated out payload on success.
+//
+// ajv@8.18.0 is transitive via @modelcontextprotocol/sdk -- do NOT add it to
+// package.json (CLAUDE.md "What NOT to Use"). strict:false at runtime; the
+// strict:true build gate lives in scripts/build-brain-packet-schema.cjs. The
+// schema is draft 2020-12, so Ajv2020 is required (ajv/dist/2020).
+//
+// SHIPPED_JOBS is the D-02 closed vocabulary (locked in 110-CONTEXT D-02).
+
+const Ajv2020 = require('ajv/dist/2020').default || require('ajv/dist/2020');
+
+const _BRAIN_PACKET_SCHEMA_PATH = process.env.MINDRIAN_BRAIN_PACKET_SCHEMA
+  || path.join(__dirname, '..', '..', 'data', 'brain-packet-schema.json');
+
+const SHIPPED_JOBS = new Set([
+  'select_methodology',
+  'suggest_next_move',
+  'detect_contradiction',
+  'summarize_neighborhood',
+  'classify_room_budding',
+  'rank_assumptions',
+  'generate_feynman_explanation',
+  'strengthen_minto',
+  'prepare_investor_brief',
+  'opportunity_react',
+  'opportunity_reflect',
+  'opportunity_rank',
+]);
+
+let _ajv = null;
+let _schemaRaw = null;
+const _jobValidators = new Map(); // job -> { in: fn, out: fn }
+
+/**
+ * Lazily compile the brain-packet schema. Reads data/brain-packet-schema.json
+ * (or process.env.MINDRIAN_BRAIN_PACKET_SCHEMA, the test seam set up by 110-01)
+ * once at first use; subsequent calls reuse the in-memory Ajv instance.
+ *
+ * NOTE on the schema's pointer shape: the 110-01 schema's per-job $defs are
+ * { in: {...}, out: {...} } -- NOT { properties: { in, out } }. So the JSON
+ * pointer for a job half is #/$defs/<job>/<half>, not the planner's interfaces
+ * sketch shape #/$defs/<job>/properties/<half>. Compiled wrappers carry the
+ * root's $defs inline because ajv 8.x cannot resolve a deep JSON pointer into
+ * a schema indexed only by its absolute $id (a known ajv@8 quirk -- the build
+ * script in scripts/build-brain-packet-schema.cjs validates the root by
+ * compiling it directly with the same Ajv2020 class).
+ */
+function _ensureSchema() {
+  if (_ajv) return;
+  _schemaRaw = JSON.parse(fs.readFileSync(_BRAIN_PACKET_SCHEMA_PATH, 'utf8'));
+  _ajv = new Ajv2020({ allErrors: true, strict: false });
+  // Pre-add the root so cross-refs (FocusNode, Origin, BankedOpportunities,
+  // BrainResponse, etc.) resolve when sub-schemas reference them. Wrapper
+  // schemas below carry $defs inline as a defensive duplicate.
+  _ajv.addSchema(_schemaRaw);
+}
+
+/**
+ * Return the memoized in/out validator for a given (job, half). Half is
+ * 'in' or 'out'. Compiles on first use.
+ *
+ * @param {string} job  - D-02 jobname (must be in SHIPPED_JOBS).
+ * @param {'in'|'out'} half
+ * @returns {Function} a compiled ajv validator function.
+ */
+function _validatorFor(job, half) {
+  _ensureSchema();
+  let pair = _jobValidators.get(job);
+  if (!pair) { pair = {}; _jobValidators.set(job, pair); }
+  if (!pair[half]) {
+    pair[half] = _ajv.compile({
+      $id: 'urn:mindrian:brain-packet:' + job + ':' + half,
+      $ref: '#/$defs/' + job + '/' + half,
+      $defs: _schemaRaw.$defs,
+    });
+  }
+  return pair[half];
+}
+
+/**
+ * Reset the lazy schema state. Test hook only -- NOT part of the public API.
+ * Used by 110-05 (the per-job validation suite) and 110-04 (the pre-commit
+ * tripwire) to swap the schema seam (MINDRIAN_BRAIN_PACKET_SCHEMA) and re-run.
+ */
+function _resetSchema() {
+  _ajv = null;
+  _schemaRaw = null;
+  _jobValidators.clear();
+}
+
+/**
+ * Best-effort memory_event log. Skips silently if opts.db is absent OR if the
+ * navigation re-export throws (Brain telemetry should never break a Brain call).
+ *
+ * @param {object} db        - SQLite db handle from openRoomDb (or undefined).
+ * @param {string} eventType - one of 'brain_packet_rejected' /
+ *                             'brain_response_rejected' / 'brain_legacy_path_used'
+ *                             (Phase 110-02 added these to EVENT_TYPES).
+ * @param {object} payload   - { job, errors, source_path, ... } scalars only.
+ */
+function _logEventBestEffort(db, eventType, payload) {
+  if (!db) return;
+  try {
+    // Lazy-require to avoid a circular load between brain-client.cjs and
+    // navigation.cjs (navigation.cjs does NOT require brain-client.cjs today,
+    // but this stays robust if a future closure of the loop ever happens).
+    require('./navigation.cjs').logMemoryEvent(db, eventType, payload || {});
+  } catch (_e) { /* best-effort */ }
+}
+
+/**
+ * Detect a "Brain doesn't recognize this tool" error in the callTool result.
+ * Per the callTool JSDoc around line ~329, the result on a server-side error
+ * is shaped { text: 'Error: ...' } (Cypher errors pass through the same way).
+ * A missing brain_packet tool will show up as -32602 / 'unknown tool' / 'No
+ * such tool' / a 404-ish marker. Be liberal: D-04 says "degrade gracefully
+ * when the Brain doesn't recognize the contract."
+ *
+ * @param {*} result
+ * @returns {boolean}
+ */
+function _looksLikeUnknownToolError(result) {
+  if (!result) return false;
+  let t = '';
+  if (typeof result === 'string') t = result;
+  else if (typeof result === 'object') t = result.text || result.error || JSON.stringify(result);
+  const s = String(t).toLowerCase();
+  return s.includes('unknown tool')
+    || s.includes('no such tool')
+    || s.includes('method not found')
+    || s.includes('-32602')
+    || (s.includes('brain_packet') && (s.includes('not') || s.includes('unknown')))
+    || s.includes('tool not found');
+}
+
+/**
+ * Unwrap the callTool result to the Brain response object the schema wants to
+ * validate. callTool returns:
+ *   - an array (the tools/call content array on a successful brain_query-style
+ *     parsed result),
+ *   - or a parsed object (when content[0] is text and parses as JSON),
+ *   - or { text: '...' } (text content that did not parse as JSON, or an error
+ *     string),
+ *   - or null (unreachable / no API key -- handled before this is called).
+ *
+ * For brain_packet specifically, the Brain side (when implemented) will return
+ * a BrainResponse-shaped JSON object: { job_id, suggestions: [...] }. Older
+ * test transports inject [{ type:'text', text: JSON.stringify(...) }] (the raw
+ * MCP content array shape). Both shapes are unwrapped to the response object.
+ *
+ * @param {*} result
+ * @returns {object}
+ */
+function _parseBrainResult(result) {
+  if (Array.isArray(result)) {
+    for (const item of result) {
+      if (item && item.type === 'text' && typeof item.text === 'string') {
+        try { return JSON.parse(item.text); } catch (_) { /* fall through */ }
+      }
+    }
+    return { suggestions: [] };
+  }
+  if (result && typeof result === 'object') {
+    // text-only error/string shape -- try to parse, else return { suggestions: [] }
+    if (typeof result.text === 'string' && !result.job_id && !result.suggestions) {
+      try { return JSON.parse(result.text); } catch (_) { return { suggestions: [] }; }
+    }
+    return result;
+  }
+  if (typeof result === 'string') {
+    try { return JSON.parse(result); } catch (_) { return { suggestions: [] }; }
+  }
+  return { suggestions: [] };
+}
+
+// ----------------------------------------------------------------------------
+// _warnLegacyOnce -- the D-10 dual-path deprecation guard.
+//
+// As of v1.13.0-beta.3 there is NO legacy free-form Brain *job* call site --
+// new job-style work goes through sendPacket(). The guard ships now as a
+// forward-looking contract: if a free-form job helper is ever added before
+// v1.14.0, it MUST call _warnLegacyOnce() first; in v1.14.0 both the helper
+// and this guard are deleted.
+//
+// query() / write() / search() / schema() / callTool() / ask() / stats() are
+// NOT "legacy" -- raw-Cypher methodology lookups carry only generic handles
+// (framework names, phase identifiers, problem-type enums) and are Part-8
+// clean by construction; they are PERMANENT.
+//
+// Module-level flag idiom mirrors checkFilePermissions._warned (the existing
+// once-per-process warning pattern in this file).
+// ----------------------------------------------------------------------------
+
+let _legacyPathWarned = false;
+
+function _warnLegacyOnce(db) {
+  if (_legacyPathWarned) return;
+  _legacyPathWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn('[mindrian-os] legacy free-form Brain job call detected. '
+    + 'Migrate to brain-client.sendPacket() -- the legacy job path is removed in v1.14.0.');
+  _logEventBestEffort(db, 'brain_legacy_path_used', {
+    source_path: 'system:brain-legacy',
+  });
+}
+
+/**
+ * Validate-then-route a Brain Context Packet. The ONLY door for typed Brain
+ * job calls.
+ *
+ * Per CONTEXT D-07 "reject hard, degrade soft":
+ *   - Bad in-packet (a programmer error in OUR code) -> throw.
+ *   - Bad origin (D-08 layer 3) -> throw.
+ *   - Unknown job -> throw.
+ *   - Brain unreachable -> { advice: null, reason: 'brain_unreachable' } (no throw).
+ *   - brain_packet tool absent on the Brain -> { advice: null, reason:
+ *     'brain_packet_tool_absent' } (no throw, no log -- D-04 graceful degrade
+ *     is NOT a bad-response situation; a half-trusted response IS one).
+ *   - Bad out-response -> { advice: null, reason: 'response_schema_invalid' }
+ *     + log brain_response_rejected. NEVER throws, NEVER partial-ingests.
+ *
+ * @param {object} packet - MUST come from lib/core/navigation.cjs::buildBrainPacket
+ *                          (D-01 chokepoint; D-08 layer 2 enforces lexically;
+ *                          D-08 layer 3 is the origin check below).
+ * @param {object} [opts] - { db?, roomDir?, __transport? }
+ *                          db        -> the SQLite handle for the memory_event log
+ *                          roomDir   -> reserved for future use; not read today
+ *                          __transport -> optional test seam: a function
+ *                                         (toolName, args) => Promise<result> that
+ *                                         replaces callTool (lets tests inject a
+ *                                         fake without require.cache surgery)
+ * @returns {Promise<object>} the validated Brain out on success; a no-advice
+ *                            sentinel on a soft-degrade.
+ * @throws on a bad in-packet, a bad origin (D-08 layer 3), or an unknown job.
+ */
+async function sendPacket(packet, opts) {
+  const o = opts || {};
+
+  // (1) D-08 layer 3 -- the belt to the schema's suspenders. Runs FIRST so a
+  //     caller who bypassed ajv still gets caught.
+  if (!packet || typeof packet.origin !== 'string') {
+    throw new Error('brain packet missing origin (D-08): packets must come from buildBrainPacket');
+  }
+  if (packet.origin === 'test_fixture' && process.env.MINDRIAN_TEST_MODE !== '1') {
+    throw new Error('brain packet origin "test_fixture" only valid when MINDRIAN_TEST_MODE=1');
+  }
+  if (packet.origin !== 'navigation_api' && packet.origin !== 'test_fixture') {
+    throw new Error('brain packet origin "' + packet.origin
+      + '" not in the closed allowlist (D-08): navigation_api | test_fixture');
+  }
+
+  // (2) Unknown-job guard.
+  if (!SHIPPED_JOBS.has(packet.job)) {
+    throw new Error('brain packet: unknown job "' + packet.job
+      + '" (not in the D-02 closed vocabulary)');
+  }
+
+  // (3) in-validation -- reject hard.
+  const inFn = _validatorFor(packet.job, 'in');
+  if (!inFn(packet)) {
+    // Pitfall 1: snapshot errors immediately -- validate.errors is overwritten
+    // on every subsequent validate() call.
+    const errsSnapshot = (inFn.errors || []).slice();
+    const errStr = errsSnapshot
+      .map(function (e) { return (e.instancePath || '(root)') + ' ' + (e.message || ''); })
+      .join('; ');
+    _logEventBestEffort(o.db, 'brain_packet_rejected', {
+      job: packet.job,
+      errors: errsSnapshot.length,
+      source_path: 'system:brain-packet',
+    });
+    throw new Error('brain packet rejected for job "' + packet.job + '": ' + errStr);
+  }
+
+  // (4) Build the wire envelope + POST. Reuse callTool's transport (it does
+  //     tools/call over Streamable HTTP + SSE-parse). Tests can inject a fake
+  //     via opts.__transport.
+  const transport = (typeof o.__transport === 'function') ? o.__transport : callTool;
+  let result;
+  try {
+    result = await transport('brain_packet', { packet: packet });
+  } catch (_e) {
+    // Network / transport error: treat like the Brain being unreachable.
+    // No log -- it is not a leak, and not a contract violation either.
+    return { advice: null, reason: 'brain_unreachable' };
+  }
+  if (result == null) {
+    // callTool returns null when there is no API key or when the HTTP layer
+    // returned a non-ok status -- functionally the same as "Brain unreachable".
+    return { advice: null, reason: 'brain_unreachable' };
+  }
+  if (_looksLikeUnknownToolError(result)) {
+    // The live Brain has no brain_packet tool yet (D-04 generalized).
+    // Degrade soft, NO brain_response_rejected log -- this is NOT a bad
+    // response; it is the absence of a contract handler.
+    return { advice: null, reason: 'brain_packet_tool_absent' };
+  }
+
+  // (5) out-validation -- reject hard but degrade soft.
+  const parsed = _parseBrainResult(result);
+  const outFn = _validatorFor(packet.job, 'out');
+  if (!outFn(parsed)) {
+    const errsSnapshot = (outFn.errors || []).slice();
+    _logEventBestEffort(o.db, 'brain_response_rejected', {
+      job: packet.job,
+      errors: errsSnapshot.length,
+      source_path: 'system:brain-packet',
+    });
+    // NEVER throw on a bad response; NEVER partial-ingest.
+    return { advice: null, reason: 'response_schema_invalid' };
+  }
+
+  // (6) Success -- the caller gets a known-good shape (typically then calls
+  //     navigation.storeBrainSuggestions).
+  return parsed;
+}
+
 module.exports = {
   isAvailable,
   getApiKey,
@@ -844,16 +1241,27 @@ module.exports = {
   write,
   search,
   smartSearch,
+  ask,
   schema,
   stats,
   enrichCausalEdges,
   hatAwareRecommend,
   suggestValidationSteps,
   getFrameworkChain,
+  // Phase 110-03 (Brain Context Packet Contract wire-level enforcement):
+  // sendPacket is the SOLE typed-packet wire path; _warnLegacyOnce is the
+  // forward-looking D-10 deprecation guard with no current call site.
+  sendPacket,
+  _warnLegacyOnce,
   // SEC-01/SEC-02 + CASCADE-06 test surface: not part of the public API.
   // See lib/memory/security-trifecta.test.cjs + brain-cache-lru.test.cjs.
   // Helpers are small and pure. sessionCache + _ensureSession + _hashKey +
   // SESSION_TTL_MS are exposed for Phase 87-07 cache-behavior tests.
+  // Phase 110-03: ajv middleware test seam (_resetSchema clears the lazy
+  //   ajv state so a test can swap MINDRIAN_BRAIN_PACKET_SCHEMA and re-run;
+  //   _setLegacyWarned resets the once-per-session deprecation flag;
+  //   _validatorFor / _parseBrainResult / _looksLikeUnknownToolError are
+  //   the helpers Plan 110-05 covers in its per-job round-trip suite).
   _test: {
     sanitizeCypherInput,
     checkFilePermissions,
@@ -861,5 +1269,12 @@ module.exports = {
     SESSION_TTL_MS,
     _hashKey,
     _ensureSession,
+    _resetSchema,
+    _validatorFor,
+    _parseBrainResult,
+    _looksLikeUnknownToolError,
+    _ensureSchema,
+    SHIPPED_JOBS,
+    _setLegacyWarned: function (v) { _legacyPathWarned = !!v; },
   },
 };