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

package/lib/core/llm-name-suggester.cjs

@@ -0,0 +1,194 @@
+'use strict';
+/*
+ * Phase 119-01 -- LLM-suggested room name resolver.
+ *
+ * One-shot Haiku 4.5 call seeded with LOCAL Phase 117 auto-explore finding +
+ * Phase 118 MVA brief sentence. Returns a venture-shaped slug suggestion (e.g.
+ * 'acme-robotics', 'quantum-imaging', 'biotech-translation').
+ *
+ * Canon Part 8 invariant: this module MUST NOT invoke any Brain endpoint.
+ * The Brain repository holds GENERIC methodology -- framework chaining rules,
+ * phase progressions -- never user-specific content. A LLM call seeded with
+ * the user's auto-explore output + MVA brief sentence is purely LOCAL: the
+ * model sees the user's content directly via the local Anthropic API path,
+ * and the model's response is consumed locally.
+ *
+ * Canon Part 8 NOTE (REVISION 2026-05-16 Warning 5 fix): this module's fetch
+ * carries user content (the auto_explore_finding summary + the mva_brief_sentence)
+ * to api.anthropic.com. Per the standard plugin LLM usage pattern (precedent:
+ * lib/core/mva-classifier.cjs, lib/agents/mva/*.cjs, lib/chat/fabric-chat.cjs),
+ * this is acceptable: the Anthropic API is the LOCAL LLM transport for the
+ * plugin. The Canon Part 8 boundary covers ONLY the Mindrian-owned Brain MCP
+ * host (the Mindrian-owned methodology repository that must never receive user
+ * data) -- NOT api.anthropic.com (the Anthropic LLM transport). The two are
+ * distinct: Brain is a Mindrian-owned methodology repository that must never
+ * receive user data; api.anthropic.com is a stateless LLM transport.
+ *
+ * Tripwire: scaffold harness Gate 3 + Test 9 grep this module for any Brain-host
+ * substring AND any brain-client require AND any fetch to a brain.* URL; all
+ * three must return 0. This module body therefore avoids the literal Brain-host
+ * hostname string entirely (the scaffold harness uses literal-grep on the
+ * forbidden substring).
+ *
+ * Cost: ~$0.0005 per first-MVA completion (Haiku 4.5 input ~800 tokens,
+ * output ~10 tokens). See CONTEXT.md Architectural Decisions item 1.
+ *
+ * Em-dash discipline: uses `--` never the U+2014 character per memory
+ * feedback_no_emdashes.md.
+ *
+ * Graceful degradation: on LLM error, returns {ok: false, suggested_name:
+ * 'untitled', ...} so the F.1 selector still renders correctly with the
+ * fallback label `[name this room: untitled]`.
+ */
+
+const FALLBACK_SUGGESTION = 'untitled';
+
+// Phase 119-01 REVISION 2026-05-16 (Blocker 2 Option A): HAIKU_MODEL_ID is the
+// project-wide source-of-truth constant. The plan's REVISION text says to
+// import HAIKU_MODEL from lib/core/mva-classifier.cjs::HAIKU_MODEL, BUT
+// inspection of that module's module.exports (verified at lib/core/mva-classifier.cjs
+// line 359-370) shows HAIKU_MODEL is a module-internal const NOT exported. Per
+// Rule 1 deviation, the constant is inlined here with provenance pointing to
+// the source-of-truth declaration at lib/core/mva-classifier.cjs:53. If a
+// future phase exports HAIKU_MODEL, replace the inline literal with a require.
+const HAIKU_MODEL_ID = 'claude-haiku-4-5';
+
+/**
+ * suggestRoomName({auto_explore_finding, mva_brief_sentence, opts})
+ * @returns {Promise<{ok, suggested_name, model_used, latency_ms, error_short?}>}
+ */
+async function suggestRoomName(args) {
+  const opts = (args && typeof args === 'object') ? args : {};
+  const autoExploreFinding = opts.auto_explore_finding || null;
+  const mvaBriefSentence = (typeof opts.mva_brief_sentence === 'string') ? opts.mva_brief_sentence : '';
+  const llmClient = opts.llmClient || null;
+
+  const t0 = Date.now();
+  try {
+    const client = llmClient || _resolveProductionLlmClient();
+    const prompt = _buildLocalPrompt(autoExploreFinding, mvaBriefSentence);
+    const response = await client.complete({
+      model: HAIKU_MODEL_ID,
+      messages: [{ role: 'user', content: prompt }],
+      max_tokens: 20,
+    });
+    const raw = (response && typeof response.content === 'string') ? response.content : '';
+    const normalized = _normalizeSlug(raw);
+    const latency_ms = Date.now() - t0;
+    if (!normalized || normalized.length === 0) {
+      return { ok: false, suggested_name: FALLBACK_SUGGESTION, model_used: HAIKU_MODEL_ID, latency_ms, error_short: 'empty_response' };
+    }
+    return { ok: true, suggested_name: normalized, model_used: HAIKU_MODEL_ID, latency_ms };
+  } catch (err) {
+    const latency_ms = Date.now() - t0;
+    const error_short = String(err && err.message || err).slice(0, 60);
+    return { ok: false, suggested_name: FALLBACK_SUGGESTION, model_used: HAIKU_MODEL_ID, latency_ms, error_short };
+  }
+}
+
+function _buildLocalPrompt(autoExploreFinding, mvaBriefSentence) {
+  // Build a short prompt from LOCAL signals ONLY. The findings array carries
+  // the top whitespace + reverse-salient + cross-domain hits from Phase 117;
+  // the MVA brief sentence is the user's first conversational turn (already
+  // local). NEVER include any Brain-derived suggestion in this prompt.
+  const findingsSummary = _summarizeFindings(autoExploreFinding);
+  return [
+    'You are naming a venture. Suggest a 2-3 word kebab-case slug that captures',
+    'the core domain. Return ONLY the slug -- no prose, no quotes, no markdown.',
+    '',
+    'Brief: ' + (mvaBriefSentence || '(no brief)'),
+    'Findings: ' + findingsSummary,
+    '',
+    'Slug:',
+  ].join('\n');
+}
+
+function _summarizeFindings(autoExploreFinding) {
+  if (!autoExploreFinding || typeof autoExploreFinding !== 'object') return '(none)';
+  const findings = Array.isArray(autoExploreFinding.findings) ? autoExploreFinding.findings : [];
+  if (findings.length === 0) return '(empty)';
+  return findings.slice(0, 3).map(function (f) {
+    const sp = (typeof f.source_pipeline === 'string') ? f.source_pipeline : 'unknown';
+    const hsi = (typeof f.hsi_score === 'number') ? f.hsi_score.toFixed(2) : '?';
+    return sp + ':' + hsi;
+  }).join(', ');
+}
+
+function _normalizeSlug(raw) {
+  if (typeof raw !== 'string') return '';
+  let slug = raw.trim().toLowerCase();
+  // Collapse whitespace to single hyphen; drop everything that's not [a-z0-9-].
+  slug = slug.replace(/\s+/g, '-');
+  slug = slug.replace(/[^a-z0-9-]/g, '');
+  slug = slug.replace(/-{2,}/g, '-');
+  slug = slug.replace(/^-+|-+$/g, '');
+  return slug;
+}
+
+// Phase 119-01 REVISION 2026-05-16 (Blocker 2 Option A): mva-agent-contract.cjs
+// exports {runAgent, validateAgentResult, AGENT_RESULT_SHAPE} ONLY -- no
+// createLlmClient factory exists. The project-wide LLM-call idiom is direct
+// fetch to https://api.anthropic.com/v1/messages with x-api-key header
+// (precedent: lib/core/mva-classifier.cjs::_callHaiku same Haiku 4.5 model,
+// same anthropic-version header pattern, same AbortController timeout).
+//
+// This module mirrors that precedent verbatim. No @anthropic-ai/sdk dependency
+// added. Canon Part 8 invariant preserved: api.anthropic.com is the LOCAL
+// Anthropic API endpoint; the Mindrian-owned Brain MCP host is NEVER contacted.
+const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
+const ANTHROPIC_VERSION = '2023-06-01';
+const LLM_TIMEOUT_MS = 5000;
+
+function _resolveProductionLlmClient() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey || typeof apiKey !== 'string' || apiKey.length === 0) {
+    throw new Error('anthropic_api_key_missing');
+  }
+  if (typeof fetch !== 'function') {
+    throw new Error('global_fetch_unavailable');
+  }
+  return {
+    complete: async function (req) {
+      const model = req.model || HAIKU_MODEL_ID;
+      const messages = Array.isArray(req.messages) ? req.messages : [];
+      const max_tokens = (typeof req.max_tokens === 'number') ? req.max_tokens : 20;
+      const ctrl = (typeof AbortController === 'function') ? new AbortController() : null;
+      const timer = ctrl ? setTimeout(function () { try { ctrl.abort(); } catch (_e) {} }, LLM_TIMEOUT_MS) : null;
+      try {
+        const res = await fetch(ANTHROPIC_URL, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': ANTHROPIC_VERSION,
+          },
+          body: JSON.stringify({ model: model, max_tokens: max_tokens, messages: messages }),
+          signal: ctrl ? ctrl.signal : undefined,
+        });
+        if (!res || !res.ok) {
+          throw new Error('anthropic_http_' + (res ? res.status : 'no_response'));
+        }
+        const j = await res.json();
+        let text = '';
+        if (j && Array.isArray(j.content)) {
+          for (const blk of j.content) {
+            if (blk && blk.type === 'text' && typeof blk.text === 'string') {
+              text += blk.text;
+            }
+          }
+        }
+        return { content: text };
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    },
+  };
+}
+
+module.exports = {
+  suggestRoomName: suggestRoomName,
+  FALLBACK_SUGGESTION: FALLBACK_SUGGESTION,
+  HAIKU_MODEL_ID: HAIKU_MODEL_ID,
+  _normalizeSlug: _normalizeSlug,
+  _buildLocalPrompt: _buildLocalPrompt,
+};

package/lib/core/llm-name-suggester.test.cjs

@@ -0,0 +1,132 @@
+'use strict';
+// Phase 119-01 Task 1 tests for lib/core/llm-name-suggester.cjs.
+// Validates HAIKU_MODEL_ID + FALLBACK_SUGGESTION + suggestRoomName happy path +
+// graceful degradation + Canon Part 8 LOCAL invariant (zero brain.mindrian
+// substrings in module source) + EVENT_TYPES floor + room_discard_partial_failure
+// membership.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const suggester = require('./llm-name-suggester.cjs');
+const memoryEvents = require('./navigation/memory-events.cjs');
+
+// ---------------------------------------------------------------------------
+// EVENT_TYPES tests (floor + named membership)
+// ---------------------------------------------------------------------------
+
+test('Test 1: EVENT_TYPES Set size grows by at least 1 above the Plan 119-00 baseline (floor >= 42)', function () {
+  assert.ok(memoryEvents.EVENT_TYPES.size >= 42,
+    'EVENT_TYPES.size must be >= 42 (38 baseline + 3 from Plan 119-00 + 1 from this plan); got ' + memoryEvents.EVENT_TYPES.size);
+});
+
+test('Test 2: room_discard_partial_failure is in EVENT_TYPES; regression check on Plan 119-00 strings preserved', function () {
+  assert.ok(memoryEvents.EVENT_TYPES.has('room_discard_partial_failure'), 'room_discard_partial_failure missing');
+  assert.ok(memoryEvents.EVENT_TYPES.has('room_auto_created'), 'Plan 119-00 string room_auto_created regressed');
+  assert.ok(memoryEvents.EVENT_TYPES.has('room_naming_decided'), 'Plan 119-00 string room_naming_decided regressed');
+  assert.ok(memoryEvents.EVENT_TYPES.has('room_discarded'), 'Plan 119-00 string room_discarded regressed');
+});
+
+test('Test 3: EVENT_TYPES object is Object.frozen (own-properties invariant)', function () {
+  assert.ok(Object.isFrozen(memoryEvents.EVENT_TYPES),
+    'EVENT_TYPES Set must be Object.frozen (own-properties; the internal Set slot is documentation-only frozen per ECMAScript spec)');
+});
+
+test('Test 4: logEvent acceptance round-trip for room_discard_partial_failure', function () {
+  // Use a real tmp room.db via room-db.cjs::openRoomDb (the canonical opener).
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'lln-suggester-test-'));
+  try {
+    const { openRoomDb, closeRoomDb } = require('./room-db.cjs');
+    const db = openRoomDb(tmpRoot);
+    try {
+      const result = memoryEvents.logEvent(db, 'room_discard_partial_failure', {
+        previous_slug: 'untitled-2026-05-16-1845',
+        partial_state: { fs_removed: true, registry_purged: false },
+        error_short: 'EBUSY',
+        source_path: 'system:room-discard-cascade',
+        created_by: 'system',
+      });
+      assert.strictEqual(result.ok, true, 'logEvent must accept room_discard_partial_failure as a valid event_type');
+      assert.match(result.eventId, /^memory_event:room_discard_partial_failure:\d+:[0-9a-f]{8}$/);
+    } finally {
+      closeRoomDb(db);
+    }
+  } finally {
+    try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_e) {}
+  }
+});
+
+// ---------------------------------------------------------------------------
+// suggestRoomName tests
+// ---------------------------------------------------------------------------
+
+test('Test 5: HAIKU_MODEL_ID constant equals claude-haiku-4-5 (mirrors lib/core/mva-classifier.cjs:53)', function () {
+  assert.strictEqual(suggester.HAIKU_MODEL_ID, 'claude-haiku-4-5');
+});
+
+test('Test 6: FALLBACK_SUGGESTION constant equals untitled (verbatim)', function () {
+  assert.strictEqual(suggester.FALLBACK_SUGGESTION, 'untitled');
+});
+
+test('Test 7: suggestRoomName happy path returns normalized slug', async function () {
+  const stub = { complete: async function () { return { content: 'acme-robotics' }; } };
+  const r = await suggester.suggestRoomName({
+    auto_explore_finding: { findings: [{ source_pipeline: 'whitespace', hsi_score: 0.83 }] },
+    mva_brief_sentence: 'Robotic precision for industrial automation.',
+    llmClient: stub,
+  });
+  assert.strictEqual(r.ok, true);
+  assert.strictEqual(r.suggested_name, 'acme-robotics');
+  assert.strictEqual(r.model_used, 'claude-haiku-4-5');
+  assert.ok(typeof r.latency_ms === 'number' && r.latency_ms >= 0);
+});
+
+test('Test 8: suggestRoomName graceful degradation on LLM error -> FALLBACK_SUGGESTION', async function () {
+  const stub = { complete: async function () { throw new Error('timeout'); } };
+  const r = await suggester.suggestRoomName({
+    auto_explore_finding: null,
+    mva_brief_sentence: '',
+    llmClient: stub,
+  });
+  assert.strictEqual(r.ok, false);
+  assert.strictEqual(r.suggested_name, 'untitled');
+  assert.strictEqual(r.model_used, 'claude-haiku-4-5');
+  assert.ok(typeof r.latency_ms === 'number' && r.latency_ms >= 0);
+  assert.ok(typeof r.error_short === 'string' && r.error_short.length > 0);
+});
+
+test('Test 9: Canon Part 8 LOCAL invariant -- grep tripwire on llm-name-suggester source', function () {
+  const src = fs.readFileSync(require.resolve('./llm-name-suggester.cjs'), 'utf8');
+  // The forbidden Brain coupling regex (from the plan scaffold harness Gate 3):
+  // brain.mindrian | require.+brain-client | fetch.+brain
+  assert.ok(!/brain\.mindrian/.test(src), 'source contains brain.mindrian substring (Canon Part 8 breach)');
+  assert.ok(!/require\([^)]*brain-client[^)]*\)/.test(src), 'source requires a brain-client module (Canon Part 8 breach)');
+  // The fetch.+brain regex would match commentary about "brain" near a fetch
+  // discussion; we narrow to actual fetch() invocations to brain.* hosts:
+  assert.ok(!/fetch\([^)]*['\"][^'\"]*brain[^'\"]*['\"]/.test(src), 'source fetches a brain.* URL (Canon Part 8 breach)');
+});
+
+test('Test 10: Canon Part 8 LOCAL invariant -- payload audit (constructed prompt contains no Brain handle)', function () {
+  const prompt = suggester._buildLocalPrompt({
+    findings: [{ source_pipeline: 'whitespace', hsi_score: 0.5 }],
+  }, 'AI-assisted protein folding for drug discovery.');
+  const serialized = JSON.stringify(prompt);
+  assert.ok(serialized.indexOf('brain.mindrian') === -1, 'prompt must not contain brain.mindrian');
+  assert.ok(serialized.indexOf('brain-client') === -1, 'prompt must not contain brain-client handle');
+});
+
+// ---------------------------------------------------------------------------
+// Em-dash invariant on the test file itself + module source
+// ---------------------------------------------------------------------------
+
+test('Test 11: zero em-dashes in llm-name-suggester source + this test file', function () {
+  const EMDASH = String.fromCharCode(0x2014);
+  const src = fs.readFileSync(require.resolve('./llm-name-suggester.cjs'), 'utf8');
+  const testSrc = fs.readFileSync(__filename, 'utf8');
+  assert.ok(src.indexOf(EMDASH) === -1, 'em-dash present in llm-name-suggester.cjs (HARD RULE)');
+  assert.ok(testSrc.indexOf(EMDASH) === -1, 'em-dash present in llm-name-suggester.test.cjs (HARD RULE)');
+});

package/lib/core/mva-agent-contract.cjs

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 1 -- mva-agent-contract.
+ *
+ * The AgentResult shape + the runAgent wrapper used by mva-dispatcher.cjs
+ * (Task 3 of this plan). Plan 118-02 implements 6 specific agents against
+ * the Agent contract documented below.
+ *
+ * AgentContext interface
+ * ----------------------
+ *   {
+ *     sentence_sha256: string,        // dispatcher-provided -- ONLY identifier passed to agents
+ *     remaining_budget_ms: number,    // dispatcher-provided
+ *   }
+ *
+ *   raw_sentence is NEVER exposed to agents (Canon Part 8 hard invariant).
+ *   Agents that need linguistic features must derive them from neighborhood-graph
+ *   queries against room.db (sentence-sha8 only), NOT from the raw sentence string.
+ *
+ *   process.env.MVA_SENTENCE is NEVER set. There is no escape hatch.
+ *
+ * Agent function signature
+ * ------------------------
+ *   async function agent(context, signal) -> { status: 'ok'|'empty', payload } | null
+ *
+ *   If the agent throws, runAgent wraps with status='error'.
+ *   If the AbortSignal fires before resolve, runAgent wraps with status='timeout'.
+ *   If the agent returns null, runAgent wraps with status='empty'.
+ *
+ * Pure CJS, node built-ins only, zero new runtime dependencies.
+ * Canon Part 8 invariants:
+ *   - NEVER serialize stack traces (stack traces can contain user content).
+ *   - Error messages capped at 200 chars (sliced to prevent user-content blow-through).
+ *   - The AgentContext object passed to the agent contains ONLY documented keys.
+ */
+'use strict';
+
+const ALLOWED_STATUSES = new Set(['ok', 'empty', 'error', 'timeout']);
+
+/**
+ * AGENT_RESULT_SHAPE -- a frozen object documenting the AgentResult shape.
+ *
+ * AgentResult = {
+ *   agent_id: string,                                 // 'brain_similar' | ... | 'dashboard_graph'
+ *   status: 'ok' | 'empty' | 'error' | 'timeout',
+ *   duration_ms: number,                              // wall-clock from runAgent invocation
+ *   payload?: any,                                    // agent-specific; opaque to dispatcher
+ *   error?: string,                                   // sanitized message (<= 200 chars)
+ * };
+ */
+const AGENT_RESULT_SHAPE = Object.freeze({
+  agent_id: 'string',
+  status: "'ok' | 'empty' | 'error' | 'timeout'",
+  duration_ms: 'number >= 0',
+  payload: 'optional any',
+  error: 'optional string'
+});
+
+/**
+ * validateAgentResult -- returns true if the result conforms to AgentResult shape.
+ *
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+function validateAgentResult(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (typeof result.agent_id !== 'string' || result.agent_id.length === 0) return false;
+  if (typeof result.status !== 'string' || !ALLOWED_STATUSES.has(result.status)) return false;
+  if (typeof result.duration_ms !== 'number' || result.duration_ms < 0) return false;
+  return true;
+}
+
+/**
+ * Sanitize an error into a short message. Drops stack traces, drops object
+ * properties, slices to 200 chars to prevent any user-content blow-through.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function sanitizeError(err) {
+  let msg;
+  if (err && typeof err === 'object' && typeof err.message === 'string') {
+    msg = err.message;
+  } else {
+    msg = String(err);
+  }
+  return msg.slice(0, 200);
+}
+
+/**
+ * runAgent -- invoke an agent function under an AbortController timeout. Catches
+ * any throw and converts to a structured AgentResult.
+ *
+ * @param {{ id: string, fn: Function }} agentDef
+ * @param {{ sentence_sha256: string }} context
+ * @param {{ timeoutMs?: number }} opts
+ * @returns {Promise<{ agent_id: string, status: string, duration_ms: number, payload?: any, error?: string }>}
+ */
+async function runAgent(agentDef, context, opts) {
+  const timeoutMs = (opts && typeof opts.timeoutMs === 'number') ? opts.timeoutMs : 35000;
+  const t0 = Date.now();
+  const controller = new AbortController();
+
+  // Build an AgentContext containing ONLY documented keys. We do not spread
+  // arbitrary caller props (defense-in-depth against accidental raw_sentence
+  // leakage). Canon Part 8 invariant.
+  const agentContext = {
+    sentence_sha256: context && context.sentence_sha256,
+    remaining_budget_ms: timeoutMs
+  };
+
+  let timer;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error('__mva_dispatcher_timeout__'));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([
+      Promise.resolve().then(() => agentDef.fn(agentContext, controller.signal)),
+      timeoutPromise
+    ]);
+
+    if (timer) clearTimeout(timer);
+
+    const duration_ms = Date.now() - t0;
+
+    if (result === null || result === undefined) {
+      return { agent_id: agentDef.id, status: 'empty', duration_ms };
+    }
+
+    // Result is { status: 'ok' | 'empty', payload }.
+    if (result && typeof result === 'object' && typeof result.status === 'string') {
+      if (result.status === 'ok' || result.status === 'empty') {
+        return {
+          agent_id: agentDef.id,
+          status: result.status,
+          duration_ms,
+          payload: result.payload
+        };
+      }
+    }
+
+    // Unknown shape -- treat as empty (defense-in-depth; agent contract violation).
+    return { agent_id: agentDef.id, status: 'empty', duration_ms };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    const duration_ms = Date.now() - t0;
+
+    if (controller.signal.aborted) {
+      return { agent_id: agentDef.id, status: 'timeout', duration_ms };
+    }
+
+    return {
+      agent_id: agentDef.id,
+      status: 'error',
+      duration_ms,
+      error: sanitizeError(err)
+    };
+  }
+}
+
+module.exports = {
+  runAgent,
+  validateAgentResult,
+  AGENT_RESULT_SHAPE
+};

package/lib/core/mva-agent-contract.test.cjs

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 1 -- mva-agent-contract tests.
+ *
+ * Tests the AgentResult shape, validateAgentResult, and runAgent wrapper.
+ * Per Canon Part 8 (Graph Boundary): AgentContext NEVER carries raw sentence;
+ * the only sentence-derived field is sentence_sha256. There is no escape hatch
+ * via process.env.MVA_SENTENCE.
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const {
+  runAgent,
+  validateAgentResult,
+  AGENT_RESULT_SHAPE
+} = require('./mva-agent-contract.cjs');
+
+test('mva-agent-contract: Test 1 -- agent returns ok wraps result', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => ({ status: 'ok', payload: { x: 1 } })
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'ok');
+  assert.deepStrictEqual(result.payload, { x: 1 });
+  assert.strictEqual(typeof result.duration_ms, 'number');
+  assert.ok(result.duration_ms >= 0);
+});
+
+test('mva-agent-contract: Test 2 -- agent throws becomes error result', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => { throw new Error('boom'); }
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'error');
+  assert.strictEqual(result.error, 'boom');
+  assert.ok(!('stack' in result), 'result must never carry stack');
+  assert.strictEqual(typeof result.duration_ms, 'number');
+});
+
+test('mva-agent-contract: Test 3 -- agent returns null becomes empty', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => null
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'empty');
+  assert.strictEqual(typeof result.duration_ms, 'number');
+});
+
+test('mva-agent-contract: Test 4 -- agent exceeds timeout returns timeout', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, signal) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 500);
+        signal.addEventListener('abort', () => {
+          clearTimeout(t);
+          reject(new Error('aborted'));
+        });
+      });
+      return { status: 'ok', payload: {} };
+    }
+  };
+  const t0 = Date.now();
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 100 }
+  );
+  const elapsed = Date.now() - t0;
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'timeout');
+  assert.ok(elapsed < 300, `elapsed ${elapsed} must be under 300ms`);
+  assert.ok(result.duration_ms >= 90, `duration_ms ${result.duration_ms} should be ~100`);
+});
+
+test('mva-agent-contract: Test 5 -- agent receives both args, signal observed', async () => {
+  let observedSignalAbortedAtStart = null;
+  let observedSignalAbortedAtEnd = null;
+  let observedSha = null;
+  let observedRemaining = null;
+  const agentDef = {
+    id: 'test',
+    fn: async (ctx, signal) => {
+      observedSignalAbortedAtStart = signal.aborted;
+      observedSha = ctx.sentence_sha256;
+      observedRemaining = ctx.remaining_budget_ms;
+      // Wait long enough to be cancelled
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 500);
+        signal.addEventListener('abort', () => {
+          clearTimeout(t);
+          observedSignalAbortedAtEnd = signal.aborted;
+          reject(new Error('aborted'));
+        });
+      });
+      return { status: 'ok', payload: {} };
+    }
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'def456' },
+    { timeoutMs: 100 }
+  );
+  assert.strictEqual(observedSignalAbortedAtStart, false, 'signal must start non-aborted');
+  assert.strictEqual(observedSignalAbortedAtEnd, true, 'signal must be aborted on timeout');
+  assert.strictEqual(observedSha, 'def456');
+  assert.strictEqual(observedRemaining, 100);
+  assert.strictEqual(result.status, 'timeout');
+});
+
+test('mva-agent-contract: Test 6 -- validateAgentResult', () => {
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'empty', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'error', duration_ms: 10, error: 'e' }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'timeout', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(validateAgentResult(null), false);
+  assert.strictEqual(validateAgentResult({}), false);
+  assert.strictEqual(validateAgentResult({ status: 'ok', duration_ms: 10 }), false);
+  assert.strictEqual(validateAgentResult({ agent_id: 'x', duration_ms: 10 }), false);
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'invalid', duration_ms: 10 }),
+    false
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok', duration_ms: -1 }),
+    false
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok' }),
+    false
+  );
+  assert.ok(AGENT_RESULT_SHAPE, 'shape doc must be exported');
+});