@mindrian_os/install 1.13.0-beta.11

package/lib/core/shallow-doc-parser.test.cjs

@@ -0,0 +1,226 @@
+'use strict';
+
+/*
+ * Phase 115-02 -- shallow-doc-parser unit tests (8 fixtures + ancillary)
+ *
+ * Test map (mirrors PLAN <behavior>):
+ *   PR-01..PR-03  parseRoleHints  3 fixtures
+ *   PV-01..PV-03  parseVentureHint  3 fixtures
+ *   PC-01         parseClaims  1 fixture
+ *   ES-01         extractShallow happy-path  1 integration fixture
+ *   ES-02         extractShallow graceful-degradation  1 fixture
+ *
+ * Navigation API is STUBBED via Module._resolveFilename redirect to a
+ * generated __nav-stub.cjs that records calls into navStub.__calls. This
+ * keeps the unit test free of room.db side effects; live integration is
+ * covered by tests/test-115-dual-path-integration.sh (Task 4).
+ *
+ * Canon Part 7 alignment: stub mirrors the (sessionId, nodeId, setBy)
+ * surface the parser writes through. The parser MUST NOT require
+ * room-db.cjs directly; that contract is enforced by a grep in <verify>.
+ */
+
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs');
+const Module = require('node:module');
+
+// ---------- Generate the navigation stub ----------
+
+const stubPath = path.resolve(__dirname, '__nav-stub.cjs');
+const navStubSource = `'use strict';
+// Auto-generated by shallow-doc-parser.test.cjs. DO NOT edit by hand; the
+// surface is defined to mirror lib/core/navigation.cjs as Phase 115-02
+// expects to consume it (sessionId/nodeId/setBy form for setFocus,
+// sessionId/eventType/payload form for recordMemoryEvent).
+const calls = { setFocus: [], memoryEvents: [], getActiveFocus: [] };
+function reset() { calls.setFocus.length = 0; calls.memoryEvents.length = 0; calls.getActiveFocus.length = 0; }
+module.exports = {
+  setFocus: function (sid, nid, sb) { calls.setFocus.push({ sid: sid, nid: nid, sb: sb }); return { ok: true, eventId: 'stub-evt-' + calls.setFocus.length }; },
+  recordMemoryEvent: function (sid, type, payload) { calls.memoryEvents.push({ sid: sid, type: type, payload: payload }); return { ok: true, eventId: 'stub-mem-' + calls.memoryEvents.length }; },
+  getActiveFocus: function (sid) { calls.getActiveFocus.push({ sid: sid }); return null; },
+  __calls: calls,
+  __reset: reset,
+};
+`;
+fs.writeFileSync(stubPath, navStubSource);
+
+// ---------- Redirect ./navigation.cjs requires from inside lib/core/ ----------
+
+const targetParserPath = path.resolve(__dirname, 'shallow-doc-parser.cjs');
+const originalResolve = Module._resolveFilename;
+Module._resolveFilename = function (request, parent, ...rest) {
+  if (request === './navigation.cjs' && parent && parent.filename === targetParserPath) {
+    return stubPath;
+  }
+  return originalResolve.call(this, request, parent, ...rest);
+};
+
+// ---------- Test scaffolding ----------
+
+let passed = 0;
+let failed = 0;
+function run(name, fn) {
+  try {
+    fn();
+    process.stdout.write('ok  ' + name + '\n');
+    passed += 1;
+  } catch (err) {
+    process.stderr.write('FAIL ' + name + '\n' + (err && err.stack ? err.stack : String(err)) + '\n');
+    failed += 1;
+  }
+}
+
+const { extractShallow, parseRoleHints, parseVentureHint, parseClaims } = require(targetParserPath);
+const navStub = require(stubPath);
+
+// ---------- parseRoleHints (3 fixtures) ----------
+
+run('PR-01 Founder of Acme Robotics -> Founder', () => {
+  const r = parseRoleHints('Founder of Acme Robotics');
+  assert.ok(r, 'parseRoleHints returned null');
+  assert.equal(r.canonical_role, 'Founder');
+  assert.equal(typeof r.confidence, 'number');
+  assert.ok(r.confidence > 0 && r.confidence <= 1);
+});
+
+run('PR-02 PhD Researcher in cancer biology, NIH-funded -> Researcher', () => {
+  const r = parseRoleHints('PhD Researcher in cancer biology, NIH-funded');
+  assert.ok(r);
+  assert.equal(r.canonical_role, 'Researcher');
+});
+
+run('PR-03 GP at Acme Ventures, $50M fund -> Investor', () => {
+  const r = parseRoleHints('GP at Acme Ventures, $50M fund');
+  assert.ok(r);
+  assert.equal(r.canonical_role, 'Investor');
+});
+
+run('PR-04 plain prose with no role hints -> null', () => {
+  const r = parseRoleHints('I have been thinking about market fit lately and the next quarter feels uncertain.');
+  assert.equal(r, null);
+});
+
+run('PR-null null input -> null', () => {
+  const r = parseRoleHints(null);
+  assert.equal(r, null);
+});
+
+// ---------- parseVentureHint (3 fixtures) ----------
+
+run('PV-01 Founder of Acme Robotics -> Acme Robotics', () => {
+  const r = parseVentureHint('Founder of Acme Robotics');
+  assert.equal(r.name, 'Acme Robotics');
+  assert.equal(r.stage, 'unknown');
+});
+
+run('PV-02 PI on NCT12345678 -> clinical-trial', () => {
+  const r = parseVentureHint('PI on NCT12345678 clinical trial');
+  assert.equal(r.name, 'NCT12345678');
+  assert.equal(r.stage, 'clinical-trial');
+});
+
+run('PV-03 plain prose graceful degradation -> null name', () => {
+  const r = parseVentureHint("I'm working on something");
+  assert.equal(r.name, null);
+  assert.equal(r.stage, 'unknown');
+});
+
+run('PV-null null input -> null name', () => {
+  const r = parseVentureHint(null);
+  assert.equal(r.name, null);
+  assert.equal(r.stage, 'unknown');
+});
+
+// ---------- parseClaims (1 fixture) ----------
+
+run('PC-01 CV with 3 bullets -> 3 claim objects', () => {
+  const text = '- Founded Acme in 2024\n- Raised $5M Series A\n- Team of 8 engineers and operators';
+  const claims = parseClaims(text);
+  assert.equal(claims.length, 3);
+  assert.ok(claims[0].text.length > 0);
+  assert.ok(claims[1].text.length > 0);
+  assert.ok(claims[2].text.length > 0);
+  assert.match(claims[0].text, /Founded Acme in 2024/);
+});
+
+run('PC-null null input -> empty array', () => {
+  const r = parseClaims(null);
+  assert.deepEqual(r, []);
+});
+
+// ---------- extractShallow integration (ES-01 happy-path) ----------
+
+run('ES-01 full CV paste -> 1 user + 1 venture + 3 claims, navigation calls', () => {
+  navStub.__reset();
+  const text = [
+    'Founder of Acme Robotics',
+    'PhD MIT 2018',
+    'NIH SBIR $2M 2023',
+    '',
+    '- Founded Acme in 2024',
+    '- Raised Seed round 2024',
+    '- Team of 6 engineers',
+  ].join('\n');
+  const t0 = Date.now();
+  const r = extractShallow(text, 'session-test-1');
+  const elapsed = Date.now() - t0;
+
+  // Result shape
+  assert.ok(r.user, 'expected user node, got ' + JSON.stringify(r.user));
+  assert.equal(r.user.canonical_role, 'Founder');
+  assert.ok(r.venture, 'expected venture node');
+  assert.equal(r.venture.name, 'Acme Robotics');
+  assert.ok(Array.isArray(r.claims));
+  assert.equal(r.claims.length, 3);
+
+  // Navigation calls: setFocus called exactly once for venture
+  assert.equal(navStub.__calls.setFocus.length, 1);
+  assert.equal(navStub.__calls.setFocus[0].sid, 'session-test-1');
+  assert.equal(navStub.__calls.setFocus[0].sb, 'auto-from-upload');
+
+  // Navigation calls: 5 node_created memory events (1 user + 1 venture + 3 claims)
+  assert.equal(navStub.__calls.memoryEvents.length, 5,
+    'expected 5 memory events, got ' + navStub.__calls.memoryEvents.length);
+  for (const ev of navStub.__calls.memoryEvents) {
+    assert.equal(ev.type, 'node_created');
+    assert.equal(ev.sid, 'session-test-1');
+  }
+
+  // Performance budget (sanity)
+  assert.ok(elapsed < 100, 'extractShallow took ' + elapsed + 'ms, expected < 100');
+});
+
+// ---------- extractShallow graceful degradation (ES-02) ----------
+
+run('ES-02 garbage input -> 0 nodes, 0 memory events, no throw', () => {
+  navStub.__reset();
+  const r = extractShallow('asdfqwerty 123 !@#$%^&*()_+', 'session-test-garbage');
+  assert.equal(r.user, null);
+  assert.equal(r.venture, null);
+  assert.deepEqual(r.claims, []);
+  assert.equal(navStub.__calls.setFocus.length, 0);
+  assert.equal(navStub.__calls.memoryEvents.length, 0);
+});
+
+run('ES-null missing sessionId -> empty result, no navigation calls', () => {
+  navStub.__reset();
+  const r = extractShallow('Founder of Acme Robotics', '');
+  assert.equal(r.user, null);
+  assert.equal(r.venture, null);
+  assert.deepEqual(r.claims, []);
+  assert.equal(navStub.__calls.setFocus.length, 0);
+});
+
+run('ES-null2 null text -> empty result', () => {
+  navStub.__reset();
+  const r = extractShallow(null, 'session-x');
+  assert.equal(r.user, null);
+  assert.equal(r.venture, null);
+  assert.deepEqual(r.claims, []);
+});
+
+// ---------- Summary ----------
+
+process.stdout.write('\nshallow-doc-parser: ' + passed + '/' + (passed + failed) + ' passed, ' + failed + ' failed\n');
+process.exit(failed === 0 ? 0 : 1);

package/lib/core/skill-activation-router.cjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-03 -- Skill Activation Router (precedence layer over legacy
+ * file-state + env activation)
+ * =====================================================================
+ * Composes navigation-engine.decide() output with the pre-91 (legacy)
+ * skill activation set into a single declarative activation decision
+ * that the UserPromptSubmit hook embeds into additionalContext.
+ *
+ * Routing precedence (Canon Part 3 + Canon Part 7):
+ *
+ *   1. engine.fire_skill is set AND validates as canonical verb
+ *      -> source = 'engine'
+ *      -> activated_skills = [canonical-cased verb]
+ *      -> suppressed_skills = engine.suppress_skills minus the fired verb
+ *      -> reason = 'engine_fire_skill_set'
+ *
+ *   2. engine.fire_skill is null/invalid AND engine.suppress_skills
+ *      is non-empty
+ *      -> source = 'mixed'
+ *      -> activated_skills = legacyActivation minus suppress_skills
+ *      -> suppressed_skills = intersection(legacyActivation, suppress_skills)
+ *      -> reason = 'engine_suppress_with_legacy'
+ *
+ *   3. engine is null OR engine.fire_skill is null AND
+ *      engine.suppress_skills is empty
+ *      -> source = 'legacy'
+ *      -> activated_skills = legacyActivation (unchanged)
+ *      -> suppressed_skills = []
+ *      -> reason = 'engine_silent_or_absent'
+ *
+ * Canon Part 3 (closed 10-verb vocabulary):
+ *   The CANONICAL_VERBS array in lib/core/navigation-engine-shared.cjs is
+ *   the single source of truth. Engine outputs MUST map to one of the 10
+ *   verbs. Unknown verbs are rejected with a 'canon_part_3_unknown_verb_
+ *   rejected' trace note and the router falls through to legacy or mixed
+ *   depending on whether suppress_skills is also populated. New verbs
+ *   require a canon amendment, NOT a runtime addition.
+ *
+ * Canon Part 7 (Reuse Before Build):
+ *   Legacy file-state + env activation is preserved. This module is a
+ *   precedence layer on top, NOT a replacement. When engine returns
+ *   { fire_skill: null, suppress_skills: [] } (the silent path), output
+ *   is byte-equivalent to pre-91 behavior.
+ *
+ * Canon Part 8 (Graph Boundary):
+ *   Pure local. Zero I/O. Zero network. Zero Brain reads. The router
+ *   never queries Brain, never embeds user content in any payload. It
+ *   composes two pre-computed inputs into a declarative output.
+ *
+ * Purity:
+ *   - No fs require (verified by Test 28-style audit; this module is
+ *     pure-function except the require of navigation-engine-shared for
+ *     CANONICAL_VERBS).
+ *   - No I/O.
+ *   - Never throws on null/non-array inputs (defensive coercion).
+ *
+ * License: BSL 1.1.
+ */
+
+const shared = require('./navigation-engine-shared.cjs');
+
+const CANONICAL_VERBS = shared.CANONICAL_VERBS;
+
+// ---------- Pure helpers ----------
+
+/**
+ * validateVerb(verb) -> boolean
+ *
+ * Returns true if verb maps (case-insensitive) to a CANONICAL_VERBS
+ * entry per Canon Part 3. Returns false on null, non-string, empty
+ * string, or unknown verb. The router uses this gate to enforce the
+ * closed-vocabulary boundary on engine outputs.
+ */
+function validateVerb(verb) {
+  if (verb === null || verb === undefined) return false;
+  if (typeof verb !== 'string') return false;
+  if (verb.length === 0) return false;
+  const lc = verb.toLowerCase();
+  for (let i = 0; i < CANONICAL_VERBS.length; i += 1) {
+    if (CANONICAL_VERBS[i].toLowerCase() === lc) return true;
+  }
+  return false;
+}
+
+/**
+ * canonicalizeVerb(verb) -> string|null
+ *
+ * Returns the canonical-cased entry from CANONICAL_VERBS that matches
+ * verb case-insensitively. Returns null when verb is not a canonical
+ * verb. The router calls this to normalize user/engine-supplied casing
+ * to the canonical form before emission (Test 12).
+ */
+function canonicalizeVerb(verb) {
+  if (verb === null || verb === undefined) return null;
+  if (typeof verb !== 'string') return null;
+  const lc = verb.toLowerCase();
+  for (let i = 0; i < CANONICAL_VERBS.length; i += 1) {
+    if (CANONICAL_VERBS[i].toLowerCase() === lc) return CANONICAL_VERBS[i];
+  }
+  return null;
+}
+
+/**
+ * coerceArray(maybeArray) -> Array
+ *
+ * Defensive coercion. Returns the input when it is an array; returns
+ * [] for any other shape (null, undefined, string, object, number).
+ * Used for both engine.suppress_skills and legacyActivation inputs.
+ */
+function coerceArray(maybeArray) {
+  if (Array.isArray(maybeArray)) return maybeArray;
+  return [];
+}
+
+/**
+ * intersection(a, b) -> Array
+ *
+ * Returns elements appearing in both a and b. Preserves a's order.
+ * Used to compute suppressed_skills (legacy ∩ engine.suppress_skills)
+ * in mixed mode.
+ */
+function intersection(a, b) {
+  const aArr = coerceArray(a);
+  const bArr = coerceArray(b);
+  if (aArr.length === 0 || bArr.length === 0) return [];
+  const bSet = new Set(bArr);
+  const out = [];
+  for (let i = 0; i < aArr.length; i += 1) {
+    if (bSet.has(aArr[i])) out.push(aArr[i]);
+  }
+  return out;
+}
+
+/**
+ * difference(a, b) -> Array
+ *
+ * Returns elements of a not present in b. Preserves a's order. Used to
+ * compute activated_skills (legacy minus engine.suppress_skills) in
+ * mixed mode and to drop a fired-verb from suppress_skills in the
+ * contradictory-decision case.
+ */
+function difference(a, b) {
+  const aArr = coerceArray(a);
+  const bArr = coerceArray(b);
+  if (bArr.length === 0) return aArr.slice();
+  const bSet = new Set(bArr);
+  const out = [];
+  for (let i = 0; i < aArr.length; i += 1) {
+    if (!bSet.has(aArr[i])) out.push(aArr[i]);
+  }
+  return out;
+}
+
+// ---------- Main entry ----------
+
+/**
+ * routeActivation(engineDecision, legacyActivation) -> {
+ *   activated_skills: string[],
+ *   suppressed_skills: string[],
+ *   source: 'engine' | 'legacy' | 'mixed',
+ *   reason: string,
+ *   trace_notes: string[]
+ * }
+ *
+ * Composes engine decision with legacy activation set. See the
+ * routing-precedence comment block at the top of this file for the
+ * three precedence rules.
+ *
+ * Pure function. Defensive on inputs (null, non-array, missing fields
+ * all coerce to safe defaults; never throws).
+ *
+ * Inputs:
+ *   engineDecision: typed decision from navigation-engine.decide(), OR
+ *                   null when the engine timed out / errored / was not
+ *                   invoked. May be a partial object; missing fields
+ *                   coerce to safe defaults.
+ *   legacyActivation: string[] of skill names that the pre-91
+ *                     (file-state + env) activation logic determined
+ *                     would fire this turn. May be null, non-array,
+ *                     or empty.
+ *
+ * Outputs (always a fresh object; never returns input references):
+ *   activated_skills: ordered list of skill names that should fire.
+ *   suppressed_skills: ordered list of skill names that should NOT fire
+ *                      this turn (informational; consumer Larry uses
+ *                      this to know which legacy activations were
+ *                      vetoed).
+ *   source: 'engine' | 'legacy' | 'mixed' (which path won).
+ *   reason: short symbolic reason code.
+ *   trace_notes: optional symbolic notes (Canon Part 3 verb rejections,
+ *                contradictory decisions resolved, etc) consumed by
+ *                /mos:explain-decision.
+ */
+function routeActivation(engineDecision, legacyActivation) {
+  const traceNotes = [];
+
+  // ---- Defensive input coercion ----
+  // Capture whether both inputs were nullish so we can flag null_inputs.
+  const bothNull =
+    (engineDecision === null || engineDecision === undefined) &&
+    (legacyActivation === null || legacyActivation === undefined);
+
+  // legacy is always an array internally; non-array shapes coerce to [].
+  const legacy = coerceArray(legacyActivation);
+
+  // engine fields read defensively. Missing engine -> treated as silent.
+  let fireSkillRaw = null;
+  let suppress = [];
+  if (engineDecision !== null && typeof engineDecision === 'object') {
+    if (engineDecision.fire_skill !== undefined) {
+      fireSkillRaw = engineDecision.fire_skill;
+    }
+    if (Array.isArray(engineDecision.suppress_skills)) {
+      suppress = engineDecision.suppress_skills.slice();
+    }
+  }
+
+  // ---- Precedence Rule 1: engine.fire_skill set + canonical verb ----
+  if (fireSkillRaw !== null && fireSkillRaw !== undefined && fireSkillRaw !== '') {
+    if (validateVerb(fireSkillRaw)) {
+      const canonical = canonicalizeVerb(fireSkillRaw);
+      // Resolve contradictory fire-vs-suppress: drop the fired verb
+      // from the suppress list so the output is internally consistent.
+      let resolvedSuppress = suppress;
+      const lcCanonical = canonical.toLowerCase();
+      const hadOverlap = suppress.some(function (s) {
+        return typeof s === 'string' && s.toLowerCase() === lcCanonical;
+      });
+      if (hadOverlap) {
+        resolvedSuppress = suppress.filter(function (s) {
+          return !(typeof s === 'string' && s.toLowerCase() === lcCanonical);
+        });
+        traceNotes.push('engine_contradictory_fire_vs_suppress_resolved');
+      }
+      return {
+        activated_skills: [canonical],
+        suppressed_skills: resolvedSuppress,
+        source: 'engine',
+        reason: 'engine_fire_skill_set',
+        trace_notes: traceNotes,
+      };
+    }
+    // Unknown / non-canonical verb. Reject with trace note and fall
+    // through to suppress-only (mixed) or legacy.
+    traceNotes.push('canon_part_3_unknown_verb_rejected');
+  }
+
+  // ---- Precedence Rule 2: engine silent on fire, but suppresses ----
+  if (suppress.length > 0) {
+    const activated = difference(legacy, suppress);
+    const suppressed = intersection(legacy, suppress);
+    return {
+      activated_skills: activated,
+      suppressed_skills: suppressed,
+      source: 'mixed',
+      reason: 'engine_suppress_with_legacy',
+      trace_notes: traceNotes,
+    };
+  }
+
+  // ---- Precedence Rule 3: full legacy fallback ----
+  return {
+    activated_skills: legacy.slice(),
+    suppressed_skills: [],
+    source: 'legacy',
+    reason: bothNull ? 'null_inputs' : 'engine_silent_or_absent',
+    trace_notes: traceNotes,
+  };
+}
+
+module.exports = {
+  routeActivation: routeActivation,
+  validateVerb: validateVerb,
+  canonicalizeVerb: canonicalizeVerb,
+  // Internal helpers exposed for test introspection only.
+  _intersection: intersection,
+  _difference: difference,
+  _coerceArray: coerceArray,
+};

package/lib/core/state-ops.cjs

@@ -0,0 +1,46 @@
+/**
+ * MindrianOS Plugin — State Operations
+ * Wraps existing Bash scripts via execSync. Does NOT rewrite Bash logic.
+ * Pure Node.js built-ins only.
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+const { safeReadFile } = require('./index.cjs');
+
+const SCRIPTS_DIR = path.resolve(__dirname, '../../scripts');
+
+/**
+ * Run compute-state script against a room directory.
+ * Returns raw stdout as string.
+ * @param {string} roomDir - Path to room directory
+ * @returns {string} Raw script output
+ */
+function computeState(roomDir) {
+  const resolved = path.resolve(roomDir);
+  const scriptPath = path.join(SCRIPTS_DIR, 'compute-state');
+  try {
+    const result = execSync(`bash "${scriptPath}" "${resolved}"`, {
+      timeout: 10000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result;
+  } catch (e) {
+    throw new Error(`compute-state failed: ${e.message}`);
+  }
+}
+
+/**
+ * Read the room's STATE.md file directly.
+ * @param {string} roomDir - Path to room directory
+ * @returns {string|null} STATE.md contents or null if not found
+ */
+function getState(roomDir) {
+  const resolved = path.resolve(roomDir);
+  return safeReadFile(path.join(resolved, 'STATE.md'));
+}
+
+module.exports = { computeState, getState };