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

package/lib/core/mva-telemetry.test.cjs

@@ -0,0 +1,196 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-03 Plan 03 Task 1 -- mva-telemetry tests.
+ *
+ * Verifies atomic JSONL append to ~/.mindrian/telemetry/v1.13/mva.jsonl,
+ * schema validation that rejects raw user content, per-event ALLOWED_FIELDS
+ * export with mva_brief_rendered carrying 'total_duration_ms' (NOT 'duration_ms'),
+ * and concurrent-emit safety.
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+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');
+
+// Use a hermetic temp HOME to isolate writes. Must be set BEFORE require so the
+// module's paths resolve against the temp HOME at module-load time. Restored
+// after each test via the cleanup helper.
+
+function mkTmpHome() {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'mva-telemetry-test-'));
+  return tmpHome;
+}
+
+function rmTmpHome(tmpHome) {
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch (_e) {}
+}
+
+// Pre-set HOME so the require below resolves paths against the temp dir.
+// Each test gets its own subdir via emit() path resolution (already env-aware).
+
+function freshTelemetry() {
+  // Re-require with cleared cache so module constants resolve against the
+  // current process.env.HOME.
+  delete require.cache[require.resolve('./mva-telemetry.cjs')];
+  return require('./mva-telemetry.cjs');
+}
+
+const SHA256_SAMPLE = crypto.createHash('sha256').update('hello world').digest('hex');
+
+test('telemetry Test 10 -- emit appends a valid JSON line to mva.jsonl', () => {
+  const tmpHome = mkTmpHome();
+  const prevHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const telemetry = freshTelemetry();
+    telemetry.emit('mva_pipeline_started', { sentence_sha256: SHA256_SAMPLE });
+    const jsonlPath = path.join(tmpHome, '.mindrian', 'telemetry', 'v1.13', 'mva.jsonl');
+    assert.ok(fs.existsSync(jsonlPath), 'jsonl file must exist');
+    const content = fs.readFileSync(jsonlPath, 'utf8');
+    const lines = content.split('\n').filter((l) => l.length > 0);
+    assert.strictEqual(lines.length, 1, 'must have exactly 1 line');
+    const parsed = JSON.parse(lines[0]);
+    assert.strictEqual(parsed.event, 'mva_pipeline_started');
+    assert.strictEqual(parsed.sentence_sha256, SHA256_SAMPLE);
+    assert.ok(typeof parsed.timestamp === 'string', 'must have ISO timestamp');
+  } finally {
+    process.env.HOME = prevHome;
+    rmTmpHome(tmpHome);
+  }
+});
+
+test('telemetry Test 11 -- validateEventPayload rejects long string fields (raw content suspicion)', () => {
+  const tmpHome = mkTmpHome();
+  const prevHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const telemetry = freshTelemetry();
+    // error_short is explicitly allowed at <= 60 chars
+    const longErrorShort = 'a'.repeat(120);
+    const v1 = telemetry.validateEventPayload('mva_agent_returned', {
+      sentence_sha256: SHA256_SAMPLE,
+      agent_id: 'brain_similar',
+      duration_ms: 100,
+      status: 'error',
+      error_short: longErrorShort
+    });
+    assert.strictEqual(v1.ok, false, 'long error_short must be rejected');
+
+    // Bare string field over 64 chars (not error_short, not sha256)
+    const v2 = telemetry.validateEventPayload('mva_agent_returned', {
+      sentence_sha256: SHA256_SAMPLE,
+      agent_id: 'a'.repeat(120),
+      duration_ms: 100,
+      status: 'ok'
+    });
+    assert.strictEqual(v2.ok, false, 'long agent_id must be rejected');
+  } finally {
+    process.env.HOME = prevHome;
+    rmTmpHome(tmpHome);
+  }
+});
+
+test('telemetry Test 12 -- validateEventPayload rejects fields not in schema', () => {
+  const tmpHome = mkTmpHome();
+  const prevHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const telemetry = freshTelemetry();
+    // 'sentence' is NOT in any ALLOWED_FIELDS entry; only sentence_sha256 is allowed
+    const v = telemetry.validateEventPayload('mva_pipeline_started', {
+      sentence_sha256: SHA256_SAMPLE,
+      sentence: 'I have a venture idea'  // forbidden field name (sentence-related)
+    });
+    assert.strictEqual(v.ok, false, 'sentence field must be rejected');
+
+    // 'raw_text' should also be rejected
+    const v2 = telemetry.validateEventPayload('mva_pipeline_started', {
+      sentence_sha256: SHA256_SAMPLE,
+      raw_text: 'something'
+    });
+    assert.strictEqual(v2.ok, false, 'raw_text field must be rejected');
+  } finally {
+    process.env.HOME = prevHome;
+    rmTmpHome(tmpHome);
+  }
+});
+
+test('telemetry Test 13 -- EVENT_TYPES + ALLOWED_FIELDS frozen, mva_brief_rendered uses total_duration_ms', () => {
+  const tmpHome = mkTmpHome();
+  const prevHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const telemetry = freshTelemetry();
+    assert.ok(Object.isFrozen(telemetry.EVENT_TYPES), 'EVENT_TYPES must be frozen');
+    assert.ok(Object.isFrozen(telemetry.ALLOWED_FIELDS), 'ALLOWED_FIELDS must be frozen');
+
+    // The 6 event types from OQ8
+    const expected = [
+      'mva_pipeline_started',
+      'mva_agent_returned',
+      'mva_brief_rendered',
+      'mva_option_selected',
+      'mva_brief_deployed',
+      'mva_pipeline_failed'
+    ];
+    for (const e of expected) {
+      assert.ok(telemetry.EVENT_TYPES.includes(e), `EVENT_TYPES must include ${e}`);
+      assert.ok(Array.isArray(telemetry.ALLOWED_FIELDS[e]), `ALLOWED_FIELDS must list ${e}`);
+    }
+
+    // The CRITICAL invariant: mva_brief_rendered uses 'total_duration_ms', NOT 'duration_ms'
+    const brendered = telemetry.ALLOWED_FIELDS.mva_brief_rendered;
+    assert.ok(brendered.includes('total_duration_ms'), 'must list total_duration_ms');
+    assert.equal(brendered.includes('duration_ms'), false, 'must NOT list duration_ms');
+
+    // Sanity: mva_agent_returned still uses duration_ms (it's the per-agent variant)
+    assert.ok(telemetry.ALLOWED_FIELDS.mva_agent_returned.includes('duration_ms'));
+  } finally {
+    process.env.HOME = prevHome;
+    rmTmpHome(tmpHome);
+  }
+});
+
+test('telemetry Test 14 -- concurrent emits produce well-formed JSONL lines', async () => {
+  const tmpHome = mkTmpHome();
+  const prevHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const telemetry = freshTelemetry();
+    // Fire 6 concurrent emits (simulating 6 parallel agents)
+    const promises = Array.from({ length: 6 }, (_, i) => {
+      return new Promise((resolve) => {
+        setImmediate(() => {
+          telemetry.emit('mva_agent_returned', {
+            sentence_sha256: SHA256_SAMPLE,
+            agent_id: `agent_${i}`,
+            duration_ms: 100 + i,
+            status: 'ok'
+          });
+          resolve();
+        });
+      });
+    });
+    await Promise.all(promises);
+
+    const jsonlPath = path.join(tmpHome, '.mindrian', 'telemetry', 'v1.13', 'mva.jsonl');
+    const content = fs.readFileSync(jsonlPath, 'utf8');
+    const lines = content.split('\n').filter((l) => l.length > 0);
+    assert.strictEqual(lines.length, 6, 'must have 6 lines');
+    for (const line of lines) {
+      const parsed = JSON.parse(line); // throws if torn
+      assert.strictEqual(parsed.event, 'mva_agent_returned');
+      assert.ok(typeof parsed.agent_id === 'string');
+    }
+  } finally {
+    process.env.HOME = prevHome;
+    rmTmpHome(tmpHome);
+  }
+});

package/lib/core/mva-vercel-deploy.cjs

@@ -0,0 +1,168 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-04 Plan 04 Task 1 -- mva-vercel-deploy.
+ *
+ * Vercel REST API direct deploy of the MVA Feynman deck HTML. Per LD2
+ * (Locked Decision 2 in 118-CONTEXT.md): NO `vercel` CLI dependency, NO
+ * `@vercel/client` SDK. Direct fetch() calls.
+ *
+ * Public surface:
+ *   deployDeck(html: string, sha8: string) -> Promise<DeployResult>
+ *   FALLBACK_DIR: string (~/.mindrian/mva/briefs)
+ *
+ * DeployResult:
+ *   On success:  { url: 'https://<subdomain>.vercel.app', deploy_duration_ms }
+ *   On failure:  { error: <code>, fallback_path, deploy_duration_ms,
+ *                  status?, error_short? }
+ *
+ * Failure codes:
+ *   - 'vercel_unavailable'   -- no VERCEL_TOKEN configured
+ *   - 'vercel_api_error'     -- API returned non-2xx (status field carries code)
+ *   - 'vercel_exception'     -- fetch threw / AbortController fired
+ *
+ * On any failure: writes the HTML to FALLBACK_DIR/<sha8>.html as the
+ * shareable receipt (the user still gets a deck, just locally).
+ *
+ * LD2 wire details:
+ *   POST https://api.vercel.com/v13/deployments
+ *   Authorization: Bearer <VERCEL_TOKEN>
+ *   Content-Type: application/json
+ *   Body: { name: 'mos-brief-<sha8>', files: [{ file: 'index.html',
+ *           data: base64(html), encoding: 'base64' }],
+ *           projectSettings: { framework: null }, target: 'production' }
+ *
+ * Timeout: 5 seconds via AbortController (the source spec's <3s budget plus
+ * safety headroom; the overall MVA budget is 45s and this fits with ample
+ * margin).
+ *
+ * Canon Part 8: the function sees ONLY `html` (already sanitized at build
+ * time by mva-deck-builder) and `sha8` (a hash of a hash). No raw sentence
+ * fields, no MVA_SENTENCE reads, no .sentence access. The Vercel request
+ * body uses base64-encoded HTML in the request payload; the URL is the bare
+ * endpoint. No user content in URLs or query strings.
+ *
+ * Pure CJS, node built-ins only (fs, path, os) plus the resolver module.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { resolveVercelKey } = require('./resolve-vercel-key.cjs');
+
+const VERCEL_API_URL = 'https://api.vercel.com/v13/deployments';
+const DEPLOY_TIMEOUT_MS = 5000;
+
+function _homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+/** @type {string} Resolved at call-time so HOME overrides in tests work. */
+const FALLBACK_DIR = path.join(_homeDir(), '.mindrian', 'mva', 'briefs');
+
+function _fallbackDir() {
+  return path.join(_homeDir(), '.mindrian', 'mva', 'briefs');
+}
+
+/**
+ * Write the rendered HTML to the local fallback path so the user still has a
+ * shareable artifact even when Vercel is unreachable / unconfigured.
+ *
+ * @param {string} html  the rendered deck HTML
+ * @param {string} sha8  the 8-char hash identifier
+ * @returns {string} absolute fallback path
+ */
+function _writeFallback(html, sha8) {
+  const dir = _fallbackDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const fallbackPath = path.join(dir, sha8 + '.html');
+  fs.writeFileSync(fallbackPath, html, 'utf8');
+  return fallbackPath;
+}
+
+/**
+ * deployDeck -- the one-shot Vercel deploy with local fallback.
+ *
+ * Best-effort by design: the rendered terminal brief is already in the user's
+ * scrollback by the time we're called; a deploy failure is a degraded reward
+ * (local file instead of public URL), not a fatal error.
+ *
+ * @param {string} html  full HTML document; will be base64-encoded for transit
+ * @param {string} sha8  8-char hash identifier (first 8 chars of sentence_sha256)
+ * @returns {Promise<{
+ *   url?: string,
+ *   error?: 'vercel_unavailable' | 'vercel_api_error' | 'vercel_exception',
+ *   status?: number,
+ *   error_short?: string,
+ *   fallback_path?: string,
+ *   deploy_duration_ms: number
+ * }>}
+ */
+async function deployDeck(html, sha8) {
+  const t0 = Date.now();
+  const key = resolveVercelKey();
+  if (!key) {
+    const fallback_path = _writeFallback(html, sha8);
+    return {
+      error: 'vercel_unavailable',
+      fallback_path,
+      deploy_duration_ms: Date.now() - t0,
+    };
+  }
+
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), DEPLOY_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(VERCEL_API_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': 'Bearer ' + key,
+      },
+      body: JSON.stringify({
+        name: 'mos-brief-' + sha8,
+        files: [{
+          file: 'index.html',
+          data: Buffer.from(html, 'utf8').toString('base64'),
+          encoding: 'base64',
+        }],
+        projectSettings: { framework: null },
+        target: 'production',
+      }),
+      signal: ctl.signal,
+    });
+    clearTimeout(timer);
+
+    if (!response.ok) {
+      const fallback_path = _writeFallback(html, sha8);
+      return {
+        error: 'vercel_api_error',
+        status: response.status,
+        fallback_path,
+        deploy_duration_ms: Date.now() - t0,
+      };
+    }
+
+    const data = await response.json();
+    return {
+      url: 'https://' + data.url,
+      deploy_duration_ms: Date.now() - t0,
+    };
+  } catch (e) {
+    clearTimeout(timer);
+    const fallback_path = _writeFallback(html, sha8);
+    return {
+      error: 'vercel_exception',
+      error_short: String((e && e.message) || e).slice(0, 60),
+      fallback_path,
+      deploy_duration_ms: Date.now() - t0,
+    };
+  }
+}
+
+module.exports = {
+  deployDeck,
+  FALLBACK_DIR,
+};

package/lib/core/mva-vercel-deploy.test.cjs

@@ -0,0 +1,239 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-04 Plan 04 Task 1 -- mva-vercel-deploy tests.
+ *
+ * Verifies the Vercel REST API direct-deploy path with fallback to local file.
+ * Mocks global.fetch via monkey-patch; uses tmp HOME for fallback paths.
+ *
+ * Canon Part 8 invariants:
+ *   - The deploy module only sees `html` (already sanitized) and `sha8` (a hash).
+ *   - It NEVER receives or transmits the raw sentence.
+ *   - The request body is base64-encoded HTML; no raw user content in URLs.
+ *
+ * Locked Decision 2 (LD2):
+ *   - Direct REST API to https://api.vercel.com/v13/deployments.
+ *   - 5-second AbortController timeout.
+ *   - Subdomain shape: mos-brief-<sha8>.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function _mkTmpHome() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mva-vercel-deploy-test-'));
+}
+
+function _cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+}
+
+function _freshRequire() {
+  const p = require.resolve('./mva-vercel-deploy.cjs');
+  delete require.cache[p];
+  // Also bust resolve-vercel-key in case the test mutates env
+  const rp = require.resolve('./resolve-vercel-key.cjs');
+  delete require.cache[rp];
+  return require('./mva-vercel-deploy.cjs');
+}
+
+test('Test 6: no VERCEL_TOKEN -> writes fallback file + returns error envelope', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  delete process.env.VERCEL_TOKEN;
+  process.env.HOME = home;
+  try {
+    const { deployDeck } = _freshRequire();
+    const result = await deployDeck('<!DOCTYPE html><html><body>test</body></html>', 'abcd1234');
+    assert.equal(result.error, 'vercel_unavailable');
+    assert.equal(typeof result.fallback_path, 'string');
+    assert.ok(result.fallback_path.endsWith(path.join('.mindrian', 'mva', 'briefs', 'abcd1234.html')));
+    assert.equal(typeof result.deploy_duration_ms, 'number');
+    assert.ok(result.deploy_duration_ms >= 0);
+    // Fallback HTML written to disk
+    const written = fs.readFileSync(result.fallback_path, 'utf8');
+    assert.ok(written.includes('<body>test</body>'));
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    _cleanup(home);
+  }
+});
+
+test('Test 7: mocked Vercel API returns 200 -> deployDeck returns https URL', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  const prevFetch = global.fetch;
+  process.env.VERCEL_TOKEN = 'test-token';
+  process.env.HOME = home;
+  global.fetch = async (_url, _opts) => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ url: 'mos-brief-abcd-xyz.vercel.app', readyState: 'READY' })
+  });
+  try {
+    const { deployDeck } = _freshRequire();
+    const result = await deployDeck('<!DOCTYPE html><html></html>', 'abcd1234');
+    assert.equal(result.url, 'https://mos-brief-abcd-xyz.vercel.app');
+    assert.equal(typeof result.deploy_duration_ms, 'number');
+    assert.ok(result.deploy_duration_ms >= 0);
+    assert.equal(result.error, undefined);
+    assert.equal(result.fallback_path, undefined);
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    if (prevFetch === undefined) { delete global.fetch; } else { global.fetch = prevFetch; }
+    _cleanup(home);
+  }
+});
+
+test('Test 8: Vercel API 5xx -> falls back to local file with vercel_api_error', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  const prevFetch = global.fetch;
+  process.env.VERCEL_TOKEN = 'test-token';
+  process.env.HOME = home;
+  global.fetch = async () => ({
+    ok: false,
+    status: 503,
+    json: async () => ({ error: { message: 'server unavailable' } })
+  });
+  try {
+    const { deployDeck } = _freshRequire();
+    const result = await deployDeck('<html></html>', 'beef5678');
+    assert.equal(result.error, 'vercel_api_error');
+    assert.equal(result.status, 503);
+    assert.ok(result.fallback_path.endsWith(path.join('.mindrian', 'mva', 'briefs', 'beef5678.html')));
+    assert.equal(typeof result.deploy_duration_ms, 'number');
+    assert.ok(fs.existsSync(result.fallback_path));
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    if (prevFetch === undefined) { delete global.fetch; } else { global.fetch = prevFetch; }
+    _cleanup(home);
+  }
+});
+
+test('Test 9: AbortController times out after 5s on hang -> fallback under 5500ms', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  const prevFetch = global.fetch;
+  process.env.VERCEL_TOKEN = 'test-token';
+  process.env.HOME = home;
+  // Hanging fetch: never resolves, but respects AbortSignal
+  global.fetch = (_url, opts) => new Promise((_resolve, reject) => {
+    if (opts && opts.signal) {
+      opts.signal.addEventListener('abort', () => {
+        const err = new Error('aborted');
+        err.name = 'AbortError';
+        reject(err);
+      });
+    }
+  });
+  try {
+    const { deployDeck } = _freshRequire();
+    const t0 = Date.now();
+    const result = await deployDeck('<html></html>', 'cafe9012');
+    const wall = Date.now() - t0;
+    // Should fall back (any error envelope, fallback_path populated)
+    assert.ok(result.fallback_path);
+    assert.ok(['vercel_exception', 'vercel_api_error', 'vercel_unavailable'].includes(result.error));
+    assert.ok(wall < 5500, 'wall-clock should be under 5.5s; got ' + wall);
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    if (prevFetch === undefined) { delete global.fetch; } else { global.fetch = prevFetch; }
+    _cleanup(home);
+  }
+});
+
+test('Test 10: deploy request body.name === mos-brief-<sha8>', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  const prevFetch = global.fetch;
+  process.env.VERCEL_TOKEN = 'test-token';
+  process.env.HOME = home;
+  let capturedBody = null;
+  global.fetch = async (_url, opts) => {
+    capturedBody = JSON.parse(opts.body);
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ url: 'mos-brief-deadbeef-1.vercel.app', readyState: 'READY' })
+    };
+  };
+  try {
+    const { deployDeck } = _freshRequire();
+    await deployDeck('<html></html>', 'deadbeef');
+    assert.ok(capturedBody);
+    assert.equal(capturedBody.name, 'mos-brief-deadbeef');
+    assert.ok(Array.isArray(capturedBody.files));
+    assert.equal(capturedBody.files.length, 1);
+    assert.equal(capturedBody.files[0].file, 'index.html');
+    assert.equal(capturedBody.files[0].encoding, 'base64');
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    if (prevFetch === undefined) { delete global.fetch; } else { global.fetch = prevFetch; }
+    _cleanup(home);
+  }
+});
+
+test('Test 11: HTML body is base64-encoded in request body, NOT in URL', async () => {
+  const home = _mkTmpHome();
+  const prev = process.env.VERCEL_TOKEN;
+  const prevHome = process.env.HOME;
+  const prevFetch = global.fetch;
+  process.env.VERCEL_TOKEN = 'test-token';
+  process.env.HOME = home;
+  let capturedUrl = null;
+  let capturedBody = null;
+  global.fetch = async (url, opts) => {
+    capturedUrl = url;
+    capturedBody = JSON.parse(opts.body);
+    return {
+      ok: true,
+      status: 200,
+      json: async () => ({ url: 'mos-brief-aaaa1111-1.vercel.app', readyState: 'READY' })
+    };
+  };
+  try {
+    const { deployDeck } = _freshRequire();
+    const html = '<!DOCTYPE html><html><body>HELLO</body></html>';
+    await deployDeck(html, 'aaaa1111');
+    // URL is the bare endpoint, no encoded HTML in it
+    assert.equal(capturedUrl, 'https://api.vercel.com/v13/deployments');
+    // Body file content is base64 of the HTML
+    const expectedBase64 = Buffer.from(html, 'utf8').toString('base64');
+    assert.equal(capturedBody.files[0].data, expectedBase64);
+    // And: the URL does NOT contain "HELLO" or any HTML literal
+    assert.ok(!String(capturedUrl).includes('HELLO'));
+    assert.ok(!String(capturedUrl).includes('<body>'));
+  } finally {
+    if (prev === undefined) { delete process.env.VERCEL_TOKEN; } else { process.env.VERCEL_TOKEN = prev; }
+    if (prevHome === undefined) { delete process.env.HOME; } else { process.env.HOME = prevHome; }
+    if (prevFetch === undefined) { delete global.fetch; } else { global.fetch = prevFetch; }
+    _cleanup(home);
+  }
+});
+
+test('Bonus: Canon Part 8 source grep -- no raw-sentence references in deploy module', () => {
+  const code = fs.readFileSync(path.join(__dirname, 'mva-vercel-deploy.cjs'), 'utf8');
+  // Strip comments before grepping (mirrors Plan 118-03 source-purity pattern)
+  const stripped = code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+  assert.equal(stripped.match(/MVA_SENTENCE/), null,
+    'mva-vercel-deploy.cjs must not reference MVA_SENTENCE');
+  assert.equal(stripped.match(/\.sentence\b/), null,
+    'mva-vercel-deploy.cjs must not read .sentence');
+  assert.equal(stripped.match(/raw_sentence/), null,
+    'mva-vercel-deploy.cjs must not reference raw_sentence');
+});