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

package/lib/core/doctor/class-m-brain-smoke.test.cjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 127-02 Task 2 (TDD RED -> GREEN) -- Class M Brain smoke probe tests.
+ *
+ * Covers BRAIN-MCP-127-08 acceptance (CONTEXT Deliverable 4):
+ *   Test 1:  LAYERS constant -- exactly 5 entries with stable ids
+ *   Test 2:  checkBrainSmoke() returns { ok, layers: [5 x {id,name,ok,reason,ms}], overall_ms }
+ *   Test 3:  L1 broken topology -> L2-L5 SKIPPED with reason "skipped-prior-layer-failed"
+ *   Test 4:  L1 OK + L2 no-key -> L3-L5 SKIPPED
+ *   Test 5:  L1 + L2 OK + L3 unreachable -> L4-L5 SKIPPED
+ *   Test 6:  L1 + L2 + L3 OK + L4 timeout -> L5 SKIPPED
+ *   Test 7:  All 5 layers pass when all mocks succeed; overall_ms < 30000
+ *   Test 8:  Each layer.ms >= 0 (sanity); ms fields are numbers
+ *   Test 9:  fixBrainSmoke is a no-op (diagnostic-only invariant)
+ *   Test 10: opts injection seams (mockResolveRoot/mockResolveKey/mockSchema/mockSpawn)
+ *
+ * Hermetic via the opts injection seams -- NO real network IO, NO real spawn.
+ * The shell harness in tests/test-127-02-doctor-class-m.sh exercises real spawn
+ * against the actual shim binary.
+ *
+ * Canon parts:
+ *   - Part 7 (reuse): LAYERS L1/L2/L3 import the existing resolver chokepoints
+ *                     (active-plugin-root, resolve-brain-key, brain-client.schema)
+ *   - Part 8 (graph boundary): the smoke probe queries brain_schema only (a
+ *                              generic methodology handle); zero user content
+ *                              egress in the smoke surface.
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const SMOKE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'doctor', 'class-m-brain-smoke.cjs');
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  if (err) process.stdout.write('    ' + (err.message || String(err)) + '\n');
+}
+
+// Helper: clean require cache so each test gets a fresh module instance with
+// fresh closure state for the opts seams.
+function freshLoad() {
+  delete require.cache[SMOKE_PATH];
+  return require(SMOKE_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: LAYERS constant shape.
+// ---------------------------------------------------------------------------
+(async function test1_layers_constant() {
+  const label = 'LAYERS constant: 5 frozen entries with stable ids';
+  try {
+    const mod = freshLoad();
+    assert.ok(Array.isArray(mod.LAYERS), 'LAYERS must be an array');
+    assert.equal(mod.LAYERS.length, 5, 'LAYERS must have exactly 5 entries');
+    const ids = mod.LAYERS.map(l => l.id);
+    assert.deepEqual(ids, [
+      'plugin_root',
+      'key_resolver',
+      'https_schema',
+      'stdio_handshake',
+      'e2e_brain_schema',
+    ], 'LAYERS ids must match the canonical 5-layer probe order');
+    for (const l of mod.LAYERS) {
+      assert.equal(typeof l.id, 'string', 'each layer has string id');
+      assert.equal(typeof l.name, 'string', 'each layer has string name');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 2: checkBrainSmoke() return shape.
+// ---------------------------------------------------------------------------
+(async function test2_return_shape() {
+  const label = 'checkBrainSmoke() returns { ok, layers:[5], overall_ms }';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      // All-pass mock chain for shape assertion
+      mockResolveRoot: () => ({ root: '/tmp/fake-root', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'], rel_types: [] }),
+      mockSpawn: async (_shimPath, opts) => ({ ok: true, reason: 'mocked ' + opts.intent }),
+    });
+    assert.equal(typeof result.ok, 'boolean', 'ok must be boolean');
+    assert.ok(Array.isArray(result.layers), 'layers must be an array');
+    assert.equal(result.layers.length, 5, 'layers must have 5 entries');
+    assert.equal(typeof result.overall_ms, 'number', 'overall_ms must be number');
+    assert.ok(result.overall_ms >= 0, 'overall_ms must be >= 0');
+    for (const l of result.layers) {
+      assert.equal(typeof l.id, 'string', 'layer.id is string');
+      assert.equal(typeof l.name, 'string', 'layer.name is string');
+      assert.equal(typeof l.ok, 'boolean', 'layer.ok is boolean');
+      assert.equal(typeof l.reason, 'string', 'layer.reason is string');
+      assert.equal(typeof l.ms, 'number', 'layer.ms is number');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 3: L1 broken -> L2..L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test3_l1_broken_cascade() {
+  const label = 'L1 broken -> L2-L5 cascade to skipped-prior-layer-failed';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: null, source: 'not-found', topology: 'not-found' }),
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].id, 'plugin_root', 'L1 id');
+    assert.equal(result.layers[0].ok, false, 'L1 must be false');
+    assert.match(result.layers[0].reason, /plugin root not resolved/i, 'L1 reason matches');
+    for (let i = 1; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 4: L1 OK + L2 no key -> L3-L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test4_l2_no_key_cascade() {
+  const label = 'L1 OK + L2 no key -> L3-L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: null, source: 'not-found', available: false, reason: 'MINDRIAN_BRAIN_KEY not set (env) ...' }),
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].ok, true, 'L1 must be true');
+    assert.equal(result.layers[1].ok, false, 'L2 must be false');
+    assert.match(result.layers[1].reason, /MINDRIAN_BRAIN_KEY not set/, 'L2 reason carries the resolver reason');
+    for (let i = 2; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 5: L1+L2 OK + L3 unreachable -> L4-L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test5_l3_unreachable_cascade() {
+  const label = 'L1+L2 OK + L3 returns null -> L4-L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => null,
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].ok, true, 'L1 ok');
+    assert.equal(result.layers[1].ok, true, 'L2 ok');
+    assert.equal(result.layers[2].ok, false, 'L3 must be false');
+    assert.match(result.layers[2].reason, /HTTPS|schema|unreachable/i, 'L3 reason matches');
+    for (let i = 3; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 6: L1+L2+L3 OK + L4 handshake timeout -> L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test6_l4_handshake_timeout() {
+  const label = 'L1+L2+L3 OK + L4 timeout -> L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, opts) => {
+        if (opts.intent === 'handshake') return { ok: false, reason: 'handshake timed out after 10000ms' };
+        return { ok: true, reason: 'should-not-be-called' };
+      },
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[3].ok, false, 'L4 must be false');
+    assert.match(result.layers[3].reason, /handshake|timeout/i, 'L4 reason matches');
+    assert.equal(result.layers[4].ok, false, 'L5 must be false (skipped)');
+    assert.equal(result.layers[4].reason, 'skipped-prior-layer-failed', 'L5 reason skipped');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 7: All 5 layers pass; overall_ms < 30000.
+// ---------------------------------------------------------------------------
+(async function test7_all_pass() {
+  const label = 'All 5 layers PASS via mocks; overall_ms < 30000 (30s budget)';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, _opts) => ({ ok: true, reason: 'mocked-success' }),
+    });
+    assert.equal(result.ok, true, 'overall must be true');
+    for (const l of result.layers) {
+      assert.equal(l.ok, true, 'layer ' + l.id + ' must be true');
+    }
+    assert.ok(result.overall_ms < 30000, 'overall_ms must be under 30s budget (got ' + result.overall_ms + ')');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 8: ms-field sanity.
+// ---------------------------------------------------------------------------
+(async function test8_ms_sanity() {
+  const label = 'Each layer.ms is non-negative number';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, _opts) => ({ ok: true, reason: 'ok' }),
+    });
+    for (const l of result.layers) {
+      assert.equal(typeof l.ms, 'number', 'layer.ms is number');
+      assert.ok(l.ms >= 0, 'layer.ms must be >= 0 (got ' + l.ms + ')');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 9: fixBrainSmoke is a no-op (diagnostic-only).
+// ---------------------------------------------------------------------------
+(async function test9_fix_is_noop() {
+  const label = 'fixBrainSmoke(result) is a no-op (diagnostic-only invariant)';
+  try {
+    const mod = freshLoad();
+    const fakeResult = { ok: false, layers: [], overall_ms: 0 };
+    const r = mod.fixBrainSmoke(fakeResult);
+    assert.equal(r.fixed, false, 'fixed must be false');
+    assert.match(r.reason, /diagnostic-only/, 'reason must indicate diagnostic-only nature');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 10: opts injection seams + Class M letter consistency.
+// ---------------------------------------------------------------------------
+(async function test10_opts_seams_and_class_m() {
+  const label = 'opts injection seams enable hermetic testing + Class M referenced in source';
+  try {
+    const mod = freshLoad();
+    // Verify all four seams individually substitute their layer.
+    let mockSchemaCalled = false;
+    let mockSpawnCalled = false;
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/seam', source: 'opts-mock', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'seam-key', source: 'opts-mock', available: true, reason: null }),
+      mockSchema: async () => { mockSchemaCalled = true; return { labels: [], rel_types: [] }; },
+      mockSpawn: async (_shimPath, _opts) => { mockSpawnCalled = true; return { ok: true, reason: 'seam-mock' }; },
+    });
+    assert.equal(result.ok, true, 'all seams provided -> overall true');
+    assert.equal(mockSchemaCalled, true, 'mockSchema seam invoked for L3');
+    assert.equal(mockSpawnCalled, true, 'mockSpawn seam invoked for L4 and L5');
+    assert.equal(result.layers[0].reason, 'resolved (source=opts-mock, topology=dev-clone)', 'L1 reason carries source');
+    // Source-level class letter check (CRITICAL: plan uses Class M, not K).
+    const src = fs.readFileSync(SMOKE_PATH, 'utf8');
+    assert.match(src, /Class[- ]?M/, 'source must reference Class M (not Class K -- K is taken by --stale-first-touch)');
+    assert.equal(src.indexOf('Class K'), -1, 'source MUST NOT reference Class K (collides with existing --stale-first-touch)');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Summary -- IIFEs above are async; collect results after a microtask drain.
+// ---------------------------------------------------------------------------
+setImmediate(function summarize() {
+  // Allow any straggling async test to settle. Two passes of setImmediate is
+  // enough for the trivial test bodies above.
+  setImmediate(function () {
+    process.stdout.write('\nPASSED: ' + passed + '\nFAILED: ' + failed + '\n');
+    process.exit(failed === 0 ? 0 : 1);
+  });
+});

package/lib/core/mcp-profiles.cjs

@@ -19,7 +19,7 @@ const { safeReadFile } = require('./index.cjs');
  *   - maxTools: soft limit on exposed tools (for context budget)
  *
  * Server keys map to entries in .mcp.json:
- *   - brain: brain.mindrian.ai (remote, Streamable HTTP)
+ *   - brain: mindrian-brain.onrender.com (remote, Streamable HTTP)
  *   - mindrian: MindrianOS local MCP server
  *   - research: web research tools
  *   - pinecone: vector search

package/lib/core/migration-snapshot.cjs

@@ -0,0 +1,172 @@
+'use strict';
+
+/*
+ * Phase 127-01 Task 1 -- pure helpers for the Phase 127 migration script
+ * (scripts/migrate-brain-mcp-from-http-to-stdio.cjs).
+ *
+ * Addresses BRAIN-MCP-127-06 (SG-2 snapshot path helper) +
+ * BRAIN-MCP-127-07 (SG-4 idempotency log + sha256 fingerprint + raw-identifier
+ * scrub).
+ *
+ * Pure module. NO network surface. NO process spawning. NO claude CLI
+ * invocations (those live in the orchestration script, Task 2). Canon Part 8
+ * delegation property: this file contains zero direct network calls.
+ *
+ * Source-name-prefixed sha256 fingerprint pattern matches TELEMETRY-121-02:
+ *   fingerprint = sha256(SOURCE_NAME_PREFIX + JSON.stringify(entry-tuple)).slice(0, 16)
+ *
+ * The 16-hex-char truncation matches lib/core/brain-client.cjs::_hashKey (64
+ * bits of key space, effectively zero collision at this volume).
+ *
+ * SG-4 raw-identifier guard: appendMigrationLog rejects any record string
+ * matching Bearer-token / UUID / long-base64-or-hex (>= 24 chars, alphabet-
+ * heterogeneous) regexes. Sha256 fingerprints (exactly 16 or 64 hex chars)
+ * are whitelisted by-length-and-alphabet so legitimate migration metadata
+ * passes through.
+ *
+ * HARD RULE: zero em-dashes in this file (hyphens only).
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SOURCE_NAME_PREFIX = 'mindrian-brain:';
+
+/**
+ * Compute a stable 16-hex-char sha256 fingerprint over a Brain MCP entry.
+ * Mirrors brain-client.cjs::_hashKey shape verbatim (sha256 truncated).
+ * Source-name prefix prevents cross-source collisions per TELEMETRY-121-02.
+ *
+ * @param {{command?: string, args?: string[], env?: object, type?: string}} entry
+ * @returns {string}
+ */
+function fingerprintEntry(entry) {
+  const e = entry || {};
+  const input = SOURCE_NAME_PREFIX + JSON.stringify({
+    command: e.command,
+    args: e.args,
+    env: e.env,
+    type: e.type,
+  });
+  return crypto.createHash('sha256').update(input).digest('hex').slice(0, 16);
+}
+
+/**
+ * Compute the pre-migration snapshot path. Replace colons with dashes for
+ * Windows / CIFS filesystem safety per Tavily A127.3 cross-platform note.
+ *
+ * @param {string} homeDir
+ * @param {string} isoTimestamp
+ * @returns {string}
+ */
+function snapshotPath(homeDir, isoTimestamp) {
+  const safe = String(isoTimestamp).replace(/:/g, '-');
+  return path.join(homeDir, '.mindrian', 'pre-migration-snapshots', safe + '.json');
+}
+
+/**
+ * Read the migration log (jsonl). Graceful when missing. Parse errors on a
+ * single line skip that line silently (project precedent: migrate-telemetry-v1
+ * uses the same shape).
+ *
+ * @param {string} homeDir
+ * @returns {Array<object>}
+ */
+function readMigrationsLog(homeDir) {
+  const logPath = path.join(homeDir, '.mindrian', 'migrations.jsonl');
+  if (!fs.existsSync(logPath)) return [];
+  let text;
+  try { text = fs.readFileSync(logPath, 'utf8'); } catch (_) { return []; }
+  const rows = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try { rows.push(JSON.parse(line)); } catch (_) { continue; }
+  }
+  return rows;
+}
+
+/**
+ * SG-4 raw-identifier guard. Recursively walk a record, scan strings for
+ * Bearer / UUID / long-base64-or-hex (>= 24 chars) shapes. Whitelist exact
+ * 16-char (truncated) and 64-char (full) sha256 by length-and-alphabet so
+ * legitimate fingerprint fields pass through. Throw on any match.
+ *
+ * @param {object} record
+ */
+function _scanForRawIdentifiers(record) {
+  const bearerRe = /Bearer\s+[A-Za-z0-9._\-]{16,}/i;
+  const uuidRe = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+  const longRe = /[A-Za-z0-9+/=_\-]{24,}/;
+  const sha256Full = /^[a-f0-9]{64}$/i;
+
+  function walk(node) {
+    if (node == null) return;
+    if (typeof node === 'string') {
+      if (bearerRe.test(node)) throw new Error('raw user identifier detected in migration log record (Bearer)');
+      if (uuidRe.test(node)) throw new Error('raw user identifier detected in migration log record (UUID)');
+      if (longRe.test(node)) {
+        if (sha256Full.test(node)) return;
+        throw new Error('raw user identifier detected in migration log record (long alphanumeric run)');
+      }
+      return;
+    }
+    if (Array.isArray(node)) { for (const v of node) walk(v); return; }
+    if (typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        if (k === 'fingerprint' && typeof v === 'string' && /^[a-f0-9]{16}$/.test(v)) continue;
+        walk(v);
+      }
+    }
+  }
+
+  walk(record);
+}
+
+/**
+ * Append a record to the migration log. Enforces SG-4 raw-identifier scrub
+ * BEFORE the write. Creates parent dir with mode 0700 (POSIX). Chmods the
+ * log file to mode 0600 after first write per SEC-02 hygiene.
+ *
+ * @param {string} homeDir
+ * @param {object} record
+ */
+function appendMigrationLog(homeDir, record) {
+  _scanForRawIdentifiers(record);
+  const dir = path.join(homeDir, '.mindrian');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const logPath = path.join(dir, 'migrations.jsonl');
+  const existed = fs.existsSync(logPath);
+  fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(logPath, 0o600); } catch (_) { /* best-effort */ }
+  }
+  return { written: true, log_path: logPath, first_write: !existed };
+}
+
+/**
+ * Return true if a prior 'removed' record exists for (sourceName, fingerprint).
+ *
+ * @param {string} homeDir
+ * @param {string} sourceName
+ * @param {string} fingerprint
+ * @returns {boolean}
+ */
+function isAlreadyMigrated(homeDir, sourceName, fingerprint) {
+  const rows = readMigrationsLog(homeDir);
+  for (const r of rows) {
+    if (r && r.source === sourceName && r.fingerprint === fingerprint && r.action === 'removed') {
+      return true;
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  fingerprintEntry,
+  snapshotPath,
+  readMigrationsLog,
+  appendMigrationLog,
+  isAlreadyMigrated,
+  _scanForRawIdentifiers,
+};

package/lib/core/migration-snapshot.test.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 127-01 Task 1 -- RED tests for lib/core/migration-snapshot.cjs
+ *
+ * 9 tests covering BRAIN-MCP-127-06 (SG-2 snapshot path helper) +
+ * BRAIN-MCP-127-07 (SG-4 idempotency log + sha256 fingerprint + raw-identifier
+ * scrub).
+ *
+ * Pure-module suite: zero network surface, zero process spawning, zero
+ * external state writes outside hermetic os.tmpdir() fixtures (mkdtempSync +
+ * rmSync recursive cleanup per Phase 87 pattern).
+ *
+ * Tests:
+ *   1. fingerprintEntry returns 16 hex chars (sha256 truncated)
+ *   2. fingerprintEntry distinguishes inputs by args[0]
+ *   3. fingerprintEntry uses source-name "mindrian-brain:" prefix (TELEMETRY-121-02 pattern)
+ *   4. snapshotPath replaces colons with dashes (Windows filesystem safety)
+ *   5. readMigrationsLog returns [] when log file does not exist
+ *   6. appendMigrationLog creates log with mode 0600 (POSIX) + subsequent read returns the record
+ *   7. isAlreadyMigrated returns true after matching record appended, false for different fingerprint
+ *   8. appendMigrationLog rejects a record containing Bearer-shaped string (SG-4 raw-identifier guard)
+ *   9. appendMigrationLog rejects a record containing UUID-shaped value (SG-4 raw-identifier guard)
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const snap = require('./migration-snapshot.cjs');
+
+function mkHome() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mig-snap-'));
+}
+
+function rmHome(h) {
+  try { fs.rmSync(h, { recursive: true, force: true }); } catch (_) {}
+}
+
+let pass = 0;
+let fail = 0;
+function t(name, fn) {
+  try {
+    fn();
+    pass++;
+    console.log('PASS: ' + name);
+  } catch (e) {
+    fail++;
+    console.error('FAIL: ' + name);
+    console.error('  ' + (e && e.message ? e.message : String(e)));
+    if (e && e.stack) console.error(e.stack.split('\n').slice(1, 4).join('\n'));
+  }
+}
+
+// ---- Test 1: 16-hex-char fingerprint ----
+t('T1 fingerprintEntry returns 16 hex chars', () => {
+  const fp = snap.fingerprintEntry({ command: 'node', args: ['x'], env: { K: 'v' }, type: 'http' });
+  assert.match(fp, /^[a-f0-9]{16}$/);
+});
+
+// ---- Test 2: distinguishes by args[0] + deterministic ----
+t('T2 fingerprintEntry distinguishes by args[0] and is deterministic', () => {
+  const a = { command: 'node', args: ['x'], env: {}, type: 'http' };
+  const b = { command: 'node', args: ['y'], env: {}, type: 'http' };
+  const fpA1 = snap.fingerprintEntry(a);
+  const fpA2 = snap.fingerprintEntry(a);
+  const fpB = snap.fingerprintEntry(b);
+  assert.equal(fpA1, fpA2, 'identical inputs must produce identical outputs');
+  assert.notEqual(fpA1, fpB, 'different args[0] must produce different fingerprints');
+});
+
+// ---- Test 3: source-name prefix ----
+t('T3 fingerprintEntry uses source-name "mindrian-brain:" prefix per TELEMETRY-121-02', () => {
+  const e = { command: 'node', args: ['x'], env: { K: 'v' }, type: 'http' };
+  const expectedInput = 'mindrian-brain:' + JSON.stringify({ command: e.command, args: e.args, env: e.env, type: e.type });
+  const expectedFp = crypto.createHash('sha256').update(expectedInput).digest('hex').slice(0, 16);
+  assert.equal(snap.fingerprintEntry(e), expectedFp);
+});
+
+// ---- Test 4: snapshotPath colon replacement ----
+t('T4 snapshotPath replaces colons with dashes for Windows filesystem safety', () => {
+  const p = snap.snapshotPath('/tmp/home', '2026-05-19T20:30:00Z');
+  assert.equal(p, path.join('/tmp/home', '.mindrian', 'pre-migration-snapshots', '2026-05-19T20-30-00Z.json'));
+});
+
+// ---- Test 5: readMigrationsLog graceful on missing ----
+t('T5 readMigrationsLog returns [] when log file does not exist', () => {
+  const h = mkHome();
+  try {
+    const r = snap.readMigrationsLog(h);
+    assert.ok(Array.isArray(r));
+    assert.equal(r.length, 0);
+  } finally {
+    rmHome(h);
+  }
+});
+
+// ---- Test 6: appendMigrationLog creates log with mode 0600 + readback ----
+t('T6 appendMigrationLog creates log with mode 0600 and round-trips via readMigrationsLog', () => {
+  const h = mkHome();
+  try {
+    const rec = { ts: '2026-05-19T00:00:00Z', source: 'mindrian-brain', fingerprint: 'abc1234567890def', action: 'removed' };
+    snap.appendMigrationLog(h, rec);
+    const logPath = path.join(h, '.mindrian', 'migrations.jsonl');
+    assert.ok(fs.existsSync(logPath), 'log file must exist after append');
+    if (process.platform !== 'win32') {
+      const mode = fs.statSync(logPath).mode & 0o777;
+      assert.equal(mode, 0o600, 'log mode must be 0600 on POSIX, got 0' + mode.toString(8));
+    }
+    const rows = snap.readMigrationsLog(h);
+    assert.ok(rows.length >= 1);
+    const found = rows.find((r) => r.fingerprint === 'abc1234567890def');
+    assert.ok(found, 'appended record must be readable');
+    assert.equal(found.action, 'removed');
+  } finally {
+    rmHome(h);
+  }
+});
+
+// ---- Test 7: isAlreadyMigrated ----
+t('T7 isAlreadyMigrated returns true after matching record appended, false for different fingerprint', () => {
+  const h = mkHome();
+  try {
+    const fp = 'abc1234567890def';
+    snap.appendMigrationLog(h, { ts: '2026-05-19T00:00:00Z', source: 'mindrian-brain', fingerprint: fp, action: 'removed' });
+    assert.equal(snap.isAlreadyMigrated(h, 'mindrian-brain', fp), true);
+    assert.equal(snap.isAlreadyMigrated(h, 'mindrian-brain', '0000000000000000'), false);
+  } finally {
+    rmHome(h);
+  }
+});
+
+// ---- Test 8: SG-4 raw-identifier guard rejects Bearer-shaped string ----
+t('T8 appendMigrationLog rejects record containing Bearer-shaped string (SG-4 invariant)', () => {
+  const h = mkHome();
+  try {
+    const badRec = {
+      ts: '2026-05-19T00:00:00Z',
+      source: 'mindrian-brain',
+      fingerprint: 'abc1234567890def',
+      action: 'removed',
+      bearer: 'Bearer abcdefghijklmnopqrstuv',
+    };
+    assert.throws(() => snap.appendMigrationLog(h, badRec), /raw user identifier/);
+  } finally {
+    rmHome(h);
+  }
+});
+
+// ---- Test 9: SG-4 raw-identifier guard rejects UUID-shaped value ----
+t('T9 appendMigrationLog rejects record containing UUID-shaped value (SG-4 invariant)', () => {
+  const h = mkHome();
+  try {
+    const badRec = {
+      ts: '2026-05-19T00:00:00Z',
+      source: 'mindrian-brain',
+      fingerprint: 'abc1234567890def',
+      action: 'removed',
+      key: 'c859eb6d-1234-5678-9abc-def012345678',
+    };
+    assert.throws(() => snap.appendMigrationLog(h, badRec), /raw user identifier/);
+  } finally {
+    rmHome(h);
+  }
+});
+
+console.log('');
+console.log('==== RESULTS ====');
+console.log('PASS: ' + pass);
+console.log('FAIL: ' + fail);
+process.exit(fail === 0 ? 0 : 1);