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

package/lib/core/mva-rule-linter.test.cjs

@@ -0,0 +1,336 @@
+'use strict';
+/*
+ * Phase 118-06 Plan 06 -- mva-rule-linter unit tests.
+ *
+ * Tests 1-7: linter library + CLI baseline (Task 1).
+ * Tests 8-11: pre-commit hook wire + WARN-5 rule-doc parity audit (Task 2).
+ *
+ * Test 3 reads LD1 from 118-CONTEXT.md (CRITICAL-1+5 -- not in this file;
+ * lives in tests/test-mva-dror-harness.cjs).
+ *
+ * Pure CJS, node built-ins only. Mirrors the Phase 118-00 in-tree runner
+ * pattern from lib/core/mva-classifier.test.cjs.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const LINTER_PATH = path.resolve(__dirname, 'mva-rule-linter.cjs');
+const CLI_PATH = path.resolve(REPO_ROOT, 'scripts', 'check-reward-before-investment.cjs');
+const HOOK_PATH = path.resolve(REPO_ROOT, 'scripts', 'hooks', 'pre-commit');
+
+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;
+  }
+}
+
+function freshLinter() {
+  delete require.cache[LINTER_PATH];
+  return require(LINTER_PATH);
+}
+
+// Create a temp dir + write fixture files there. Cleanup is best-effort
+// (left in place if a test throws so a human can inspect).
+function mkTempCommandsDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mva-rule-linter-'));
+  return dir;
+}
+
+function writeFixture(dir, filename, body) {
+  fs.writeFileSync(path.join(dir, filename), body, 'utf8');
+}
+
+// ---------- T1: compliant command passes ----------
+
+run('T1 compliant command: interactive_first_reward present + valid -> compliant', () => {
+  const { scanCommands } = freshLinter();
+  const dir = mkTempCommandsDir();
+  writeFixture(dir, 'good.md', [
+    '---',
+    'name: good',
+    'description: A command that follows the rule',
+    'interactive_first_reward: reframe_question',
+    '---',
+    '',
+    '# good',
+  ].join('\n'));
+  const result = scanCommands(dir);
+  assert.equal(result.compliant.length, 1, 'expected 1 compliant, got ' + JSON.stringify(result));
+  assert.equal(result.missing.length, 0);
+  assert.equal(result.invalid.length, 0);
+  assert.equal(result.ok, true);
+  assert.equal(result.compliant[0].value, 'reframe_question');
+});
+
+// ---------- T2: missing field fails ----------
+
+run('T2 missing field: frontmatter present but no interactive_first_reward -> missing', () => {
+  const { scanCommands } = freshLinter();
+  const dir = mkTempCommandsDir();
+  writeFixture(dir, 'forgot.md', [
+    '---',
+    'name: forgot',
+    'description: A command that forgot the field',
+    '---',
+    '',
+    '# forgot',
+  ].join('\n'));
+  const result = scanCommands(dir);
+  assert.equal(result.compliant.length, 0);
+  assert.equal(result.missing.length, 1);
+  assert.equal(result.invalid.length, 0);
+  assert.equal(result.ok, false);
+  assert.equal(result.missing[0].reason, 'missing_field');
+});
+
+// ---------- T3: invalid value fails ----------
+
+run('T3 invalid value: typo / unknown reward type -> invalid', () => {
+  const { scanCommands } = freshLinter();
+  const dir = mkTempCommandsDir();
+  writeFixture(dir, 'typo.md', [
+    '---',
+    'name: typo',
+    'description: A command with a typo in the reward field',
+    'interactive_first_reward: gibberish',
+    '---',
+  ].join('\n'));
+  const result = scanCommands(dir);
+  assert.equal(result.invalid.length, 1);
+  assert.equal(result.invalid[0].reason, 'invalid_value');
+  assert.equal(result.invalid[0].value, 'gibberish');
+  assert.equal(result.ok, false);
+});
+
+// ---------- T4: --none (scripting only) accepted verbatim ----------
+
+run('T4 --none (scripting only) verbatim accepted per rule doc line 81', () => {
+  const { validateFrontmatter } = freshLinter();
+  const r = validateFrontmatter({
+    name: 'cron-job',
+    interactive_first_reward: '--none (scripting only)',
+  });
+  assert.equal(r.ok, true, 'expected --none (scripting only) to validate; got ' + JSON.stringify(r));
+  assert.equal(r.value, '--none (scripting only)');
+});
+
+// ---------- T5: every REWARD_TYPES enum value accepted ----------
+
+run('T5 every REWARD_TYPES enum value accepted', () => {
+  const { validateFrontmatter, REWARD_TYPES } = freshLinter();
+  // Convert frozen Set to array for iteration -- check every entry.
+  for (const v of REWARD_TYPES) {
+    const r = validateFrontmatter({ interactive_first_reward: v });
+    assert.equal(r.ok, true, 'expected ' + JSON.stringify(v) + ' to validate; got ' + JSON.stringify(r));
+  }
+  // And spot-check the 5 named ones (plus the scripting opt-out = 6 total).
+  const expected = [
+    'reframe_question',
+    'instant_brief',
+    'schema_preview',
+    'calibration_distribution_preview',
+    'paragraph_preview',
+    '--none (scripting only)',
+  ];
+  for (const v of expected) {
+    assert.ok(REWARD_TYPES.has(v), 'REWARD_TYPES missing canonical entry: ' + v);
+  }
+});
+
+// ---------- T6: no-frontmatter file degrades gracefully ----------
+
+run('T6 file without ANY frontmatter: degrades to missing (does NOT crash)', () => {
+  const { scanCommands } = freshLinter();
+  const dir = mkTempCommandsDir();
+  writeFixture(dir, 'legacy.md', '# legacy command\n\nNo frontmatter at all.\n');
+  const result = scanCommands(dir);
+  assert.equal(result.missing.length, 1);
+  assert.equal(result.missing[0].reason, 'no_frontmatter');
+  assert.equal(result.invalid.length, 0);
+});
+
+// ---------- T7: CLI spawn -- compliant -> exit 0; missing -> exit 1 ----------
+
+run('T7 CLI spawn: compliant dir exits 0; missing-field dir exits 1 with offender on stderr', () => {
+  // Subtest A: all compliant -> exit 0.
+  const dirGood = mkTempCommandsDir();
+  writeFixture(dirGood, 'one.md', [
+    '---',
+    'name: one',
+    'interactive_first_reward: instant_brief',
+    '---',
+  ].join('\n'));
+  const okResult = spawnSync(process.execPath, [CLI_PATH, dirGood], { encoding: 'utf8' });
+  assert.equal(okResult.status, 0, 'expected exit 0 on compliant; got ' + okResult.status + '\nstdout: ' + okResult.stdout + '\nstderr: ' + okResult.stderr);
+  assert.ok(/the rule holds/.test(okResult.stdout), 'expected Larry-voice success on stdout; got: ' + okResult.stdout);
+
+  // Subtest B: missing field -> exit 1, offender named on stderr.
+  const dirBad = mkTempCommandsDir();
+  writeFixture(dirBad, 'broken.md', [
+    '---',
+    'name: broken',
+    'description: A command that forgot the field',
+    '---',
+  ].join('\n'));
+  const badResult = spawnSync(process.execPath, [CLI_PATH, dirBad], { encoding: 'utf8' });
+  assert.equal(badResult.status, 1, 'expected exit 1 on missing; got ' + badResult.status);
+  assert.ok(/broken\.md/.test(badResult.stderr), 'expected stderr to name broken.md; got: ' + badResult.stderr);
+  assert.ok(/missing_field/.test(badResult.stderr), 'expected stderr to mention missing_field reason; got: ' + badResult.stderr);
+});
+
+// ---------- T8: hook is wired (CRITICAL-4 invariant) ----------
+
+run('T8 hook wired (CRITICAL-4): scripts/hooks/pre-commit references check-reward-before-investment.cjs', () => {
+  const hook = fs.readFileSync(HOOK_PATH, 'utf8');
+  assert.ok(
+    hook.includes('check-reward-before-investment.cjs'),
+    'hooks/pre-commit must reference check-reward-before-investment.cjs (CRITICAL-4); got hook of length ' + hook.length
+  );
+});
+
+// ---------- T9: scaffold E2E (CRITICAL-4) -- temp git repo, staged offender, hook blocks ----------
+
+run('T9 scaffold E2E (CRITICAL-4): hook blocks a staged commands/foo.md that lacks the field', () => {
+  // Create an isolated temp git repo with a copy of our hook + scripts + lib.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mva-precommit-e2e-'));
+
+  // Initialize bare git repo
+  const init = spawnSync('git', ['init', '-q'], { cwd: tmp, encoding: 'utf8' });
+  if (init.status !== 0) {
+    // Skip if git is unavailable in this environment (exit 77 = POSIX skip).
+    process.stderr.write('T9 skipped: git init failed; env=' + init.stderr + '\n');
+    return;
+  }
+  // Local identity so commit (if ever attempted) wouldn't fail on identity --
+  // we never actually commit; the hook is run directly via bash.
+  spawnSync('git', ['config', 'user.email', 'test@example.invalid'], { cwd: tmp });
+  spawnSync('git', ['config', 'user.name', 'Test'], { cwd: tmp });
+
+  // Recreate the relevant directory structure inside the temp repo so the
+  // hook can resolve paths the same way it does in the real repo. We mirror:
+  //   <tmp>/scripts/hooks/pre-commit
+  //   <tmp>/scripts/check-reward-before-investment.cjs
+  //   <tmp>/lib/core/mva-rule-linter.cjs
+  //   <tmp>/commands/foo.md  (the offender)
+  fs.mkdirSync(path.join(tmp, 'scripts', 'hooks'), { recursive: true });
+  fs.mkdirSync(path.join(tmp, 'lib', 'core'), { recursive: true });
+  fs.mkdirSync(path.join(tmp, 'commands'), { recursive: true });
+
+  fs.copyFileSync(HOOK_PATH, path.join(tmp, 'scripts', 'hooks', 'pre-commit'));
+  fs.copyFileSync(CLI_PATH, path.join(tmp, 'scripts', 'check-reward-before-investment.cjs'));
+  fs.copyFileSync(LINTER_PATH, path.join(tmp, 'lib', 'core', 'mva-rule-linter.cjs'));
+
+  // Install the hook into .git/hooks/
+  const installedHook = path.join(tmp, '.git', 'hooks', 'pre-commit');
+  fs.copyFileSync(HOOK_PATH, installedHook);
+  fs.chmodSync(installedHook, 0o755);
+
+  // The offender: commands/foo.md with NO interactive_first_reward field.
+  const offenderPath = path.join(tmp, 'commands', 'foo.md');
+  fs.writeFileSync(offenderPath, [
+    '---',
+    'name: foo',
+    'description: test command without the rule field',
+    '---',
+    '',
+    '# foo',
+  ].join('\n'), 'utf8');
+
+  // Stage the offender
+  spawnSync('git', ['add', 'commands/foo.md'], { cwd: tmp });
+
+  // Run the hook directly. The Phase 87-01a guard runs BEFORE the linter
+  // block; commands/ has no .room-root sentinel so the ROOM.md/MINTO.md
+  // invariant skips (per the find_room_root scoping). The Phase 122
+  // build-command-registry --check guard would run if scripts/build-command
+  // -registry.cjs exists in the temp repo -- we did NOT copy it, so that
+  // block is a no-op. That leaves OUR linter block as the gating check.
+  //
+  // The linter block must:
+  //   1. detect that commands/foo.md is staged
+  //   2. invoke node scripts/check-reward-before-investment.cjs
+  //   3. propagate the non-zero exit
+  //
+  // We invoke the hook with `bash` so the BASH_SOURCE machinery works.
+  const hookResult = spawnSync('bash', [installedHook], { cwd: tmp, encoding: 'utf8' });
+
+  // The hook should exit non-zero. The stderr should mention foo.md.
+  assert.notEqual(
+    hookResult.status, 0,
+    'expected non-zero exit from pre-commit hook with missing-field commands/foo.md staged; got ' + hookResult.status +
+    '\nstdout: ' + hookResult.stdout + '\nstderr: ' + hookResult.stderr
+  );
+  // The hook should mention foo.md somewhere in its diagnostic output (either
+  // stdout or stderr is fine -- the linter writes the offender to stderr;
+  // the hook's wrapper line is on stderr too).
+  const combined = (hookResult.stdout || '') + (hookResult.stderr || '');
+  assert.ok(
+    /foo\.md/.test(combined),
+    'expected hook diagnostic to name foo.md; combined output: ' + combined
+  );
+});
+
+// ---------- T10: WARN-5 -- new-project.md carries `instant_brief` (NOT reframe_question) ----------
+
+run('T10 WARN-5: commands/new-project.md declares interactive_first_reward: instant_brief', () => {
+  const { parseFrontmatter } = freshLinter();
+  const npPath = path.resolve(REPO_ROOT, 'commands', 'new-project.md');
+  const fm = parseFrontmatter(fs.readFileSync(npPath, 'utf8'));
+  assert.ok(fm, 'commands/new-project.md must have parseable frontmatter');
+  assert.equal(
+    fm.interactive_first_reward,
+    'instant_brief',
+    'commands/new-project.md must carry interactive_first_reward: instant_brief (WARN-5; rule doc line 56-58 prescribes Instant Brief, NOT reframe_question); got: ' + JSON.stringify(fm.interactive_first_reward)
+  );
+});
+
+// ---------- T11: WARN-5 audit -- 4-command rule-doc parity ----------
+
+run('T11 WARN-5 audit: 4 named commands match rule-doc remediation column', () => {
+  const { parseFrontmatter } = freshLinter();
+  // Per docs/reward-before-investment-rule.md (the canonical in-repo copy
+  // shipped by Plan 06 Task 2; the prescriptions live at lines 56-70 of the
+  // source ~/MindrianRooms/.../reward-before-investment-rule.md):
+  //   new-project   -> instant_brief                    (line 56-58)
+  //   file-meeting  -> paragraph_preview                (line 60-62)
+  //   grade         -> calibration_distribution_preview (line 64-66)
+  //   onboard       -> reframe_question                 (line 68-70)
+  const prescribed = {
+    'new-project.md': 'instant_brief',
+    'file-meeting.md': 'paragraph_preview',
+    'grade.md': 'calibration_distribution_preview',
+    'onboard.md': 'reframe_question',
+  };
+  for (const [filename, expected] of Object.entries(prescribed)) {
+    const fpath = path.resolve(REPO_ROOT, 'commands', filename);
+    const fm = parseFrontmatter(fs.readFileSync(fpath, 'utf8'));
+    assert.ok(fm, 'commands/' + filename + ' must have parseable frontmatter');
+    assert.equal(
+      fm.interactive_first_reward,
+      expected,
+      'commands/' + filename + ' declares ' + JSON.stringify(fm.interactive_first_reward) +
+      ' but rule doc prescribes ' + JSON.stringify(expected) + ' (WARN-5 4-command parity audit)'
+    );
+  }
+});
+
+// ---------- summary ----------
+
+process.stdout.write('\nmva-rule-linter tests: ' + passed + '/' + (passed + failed) + ' passed\n');
+if (failed > 0) {
+  process.exit(1);
+}
+process.exit(0);

package/lib/core/mva-state.cjs

@@ -0,0 +1,159 @@
+'use strict';
+/*
+ * Phase 118-00 Plan 00 -- mva-state: session-scoped state I/O for the
+ * 30-Second MVA pipeline. The wire between Plan 118-00 (this plan, writer)
+ * and Plans 118-01..05 (readers + dispatch).
+ *
+ * State file:  ~/.mindrian/mva/<session-id>.json
+ *   session-id = process.env.CLAUDE_SESSION_ID || 'default'
+ *
+ * Schema:
+ *   {
+ *     sentence_sha256:        sha256 hex of the user's prompt sentence (64 chars)
+ *                             -- NEVER the raw sentence (Canon Part 8)
+ *     classified_at:          epoch ms
+ *     classifier_source:      'heuristic' | 'heuristic_fallback' | 'language_detect' | 'haiku-4-5'
+ *     classifier_confidence:  'high' | 'medium' | 'low'
+ *     locale:                 'en' | 'he'
+ *     hebrew_refusal:         true   -- only present when LD1 short-circuit fired
+ *     pipeline_status:        'pending' | 'running' | 'complete'
+ *     started_at:             epoch ms (set by markRunning)
+ *     completed_at:           epoch ms (set by markComplete)
+ *   }
+ *
+ * Atomicity: every write goes to <session-id>.json.tmp.<pid>.<rand> then
+ * fs.renameSync to <session-id>.json. Mirrors the lib/core/rs-egress-telemetry
+ * tmp+rename pattern (Phase 89.2 Plan 01). A crashed writer cannot leave a
+ * half-JSON readers would choke on.
+ *
+ * Canon Part 8: file is LOCAL only. Zero network surface. The sentence_sha256
+ * is a one-way hash; no path from this file back to the raw prompt.
+ *
+ * Pure CJS, node built-ins only (fs, path, os).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+function homeDir() {
+  // Match the env-aware home resolution pattern from resolve-brain-key.cjs
+  // so hermetic tests overriding process.env.HOME on Linux/POSIX work
+  // (os.homedir reads /etc/passwd and ignores process.env.HOME).
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function stateDir() {
+  return path.join(homeDir(), '.mindrian', 'mva');
+}
+
+function sessionId() {
+  const s = process.env.CLAUDE_SESSION_ID;
+  return (typeof s === 'string' && s.length > 0) ? s : 'default';
+}
+
+function stateFile() {
+  return path.join(stateDir(), sessionId() + '.json');
+}
+
+function ensureDir() {
+  const dir = stateDir();
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (_e) {
+    // best-effort; the writeFileSync will surface a clearer error
+  }
+}
+
+/**
+ * Atomic write: writeFileSync to a tmp path, then renameSync into place.
+ * Throws on fs error -- callers (hook scripts) MUST wrap in try/catch and
+ * exit 0 to honor the Phase 117 hook-best-effort contract.
+ */
+function _atomicWrite(target, body) {
+  ensureDir();
+  const tmp = target + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
+  fs.writeFileSync(tmp, body, 'utf8');
+  fs.renameSync(tmp, target);
+}
+
+/**
+ * Read the current state file. Returns null on absent / parse-error /
+ * read-error (graceful degradation; readers treat null as "no pending").
+ */
+function readPending() {
+  let raw;
+  try {
+    raw = fs.readFileSync(stateFile(), 'utf8');
+  } catch (_e) {
+    return null; // ENOENT or permission -- treat as no state
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (_e) {
+    return null; // corrupt file -- treat as no state
+  }
+}
+
+/**
+ * Write the venture-classified or hebrew-refusal payload. Initializes
+ * pipeline_status='pending' so the dispatcher (Plan 118-01) knows to fire.
+ *
+ * @param {object} payload   Must include sentence_sha256, classified_at,
+ *                           classifier_source, classifier_confidence, locale.
+ *                           May include hebrew_refusal:true (per LD1).
+ */
+function writePending(payload) {
+  const body = Object.assign({}, payload, { pipeline_status: 'pending' });
+  _atomicWrite(stateFile(), JSON.stringify(body));
+}
+
+/**
+ * Transition pipeline_status -> 'running'. The dispatcher calls this when
+ * it begins the 6-agent fan-out so a re-entrant UserPromptSubmit does not
+ * re-fire the pipeline for an in-flight session.
+ */
+function markRunning() {
+  const cur = readPending();
+  if (!cur) return; // nothing to mark; silent
+  const body = Object.assign({}, cur, {
+    pipeline_status: 'running',
+    started_at: Date.now(),
+  });
+  _atomicWrite(stateFile(), JSON.stringify(body));
+}
+
+/**
+ * Transition pipeline_status -> 'complete'. The orchestrator calls this
+ * after the deck deploys (Plan 118-04) or the budget exhausts gracefully.
+ */
+function markComplete() {
+  const cur = readPending();
+  if (!cur) return;
+  const body = Object.assign({}, cur, {
+    pipeline_status: 'complete',
+    completed_at: Date.now(),
+  });
+  _atomicWrite(stateFile(), JSON.stringify(body));
+}
+
+/**
+ * @returns {boolean} true if a pipeline is currently running for this session
+ *   (the hook uses this to gate re-fire on a second UserPromptSubmit).
+ */
+function isAlreadyRunning() {
+  const cur = readPending();
+  return !!(cur && cur.pipeline_status === 'running');
+}
+
+module.exports = {
+  writePending,
+  readPending,
+  markRunning,
+  markComplete,
+  isAlreadyRunning,
+  stateDir,
+  // exposed for tests + downstream plans that need the canonical path
+  stateFile,
+  sessionId,
+};

package/lib/core/mva-telemetry.cjs

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-03 Plan 03 -- mva-telemetry.
+ *
+ * JSONL writer for the 6 Phase 121 MVA event types. Atomic append to
+ * ~/.mindrian/telemetry/v1.13/mva.jsonl. Schema-enforced (rejects events
+ * with raw user content; per-event ALLOWED_FIELDS is the source of truth
+ * for Plan 118-06's Dror harness grep test).
+ *
+ * Per Plan 118-03 OQ8 (resolved): the 6 event types are
+ *   mva_pipeline_started, mva_agent_returned, mva_brief_rendered,
+ *   mva_option_selected, mva_brief_deployed, mva_pipeline_failed.
+ *
+ * CRITICAL invariant (WARN-2 from iteration 2): the mva_brief_rendered
+ * event uses `total_duration_ms` (NOT `duration_ms`). Plan 118-06's
+ * Dror harness greps ALLOWED_FIELDS.mva_brief_rendered to assert this.
+ *
+ * Canon Part 8 (LOCAL telemetry):
+ *   - Sentence-related identifier is sentence_sha256 ONLY (one-way hash).
+ *   - Every string field is capped (sentence_sha256=64 exact, error_short<=60,
+ *     other strings<=64) to prevent raw user content from sneaking through.
+ *   - Fields not in ALLOWED_FIELDS for the event type are rejected.
+ *
+ * Atomic append: fs.appendFileSync writes a single short line. POSIX
+ * append semantics guarantee atomicity for writes within PIPE_BUF (4096
+ * bytes on Linux). Our lines are < 512 bytes, well below the limit.
+ *
+ * Pure CJS, node built-ins only.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// ---------- Frozen invariants ----------
+
+const EVENT_TYPES = Object.freeze([
+  'mva_pipeline_started',
+  'mva_agent_returned',
+  'mva_brief_rendered',
+  'mva_option_selected',
+  'mva_brief_deployed',
+  'mva_pipeline_failed'
+]);
+
+// Per-event scalar field schema. Source-of-truth for Plan 118-06 Dror harness.
+// CRITICAL: mva_brief_rendered uses 'total_duration_ms' (NOT 'duration_ms').
+const ALLOWED_FIELDS = Object.freeze({
+  mva_pipeline_started: Object.freeze(['sentence_sha256']),
+  mva_agent_returned:   Object.freeze(['sentence_sha256', 'agent_id', 'duration_ms', 'status', 'error_short']),
+  mva_brief_rendered:   Object.freeze(['sentence_sha256', 'total_duration_ms', 'agent_count_ok', 'agent_count_failed']),
+  mva_option_selected:  Object.freeze(['sentence_sha256', 'option_id', 'time_to_click_ms']),
+  mva_brief_deployed:   Object.freeze(['sentence_sha256', 'vercel_subdomain_hash', 'deploy_duration_ms', 'status', 'error_short']),
+  mva_pipeline_failed:  Object.freeze(['sentence_sha256', 'total_duration_ms', 'error_short'])
+});
+
+// String-length caps. error_short is special-cased to <= 60.
+// sentence_sha256 must be exactly 64 hex chars.
+const MAX_STRING_LEN = 64;
+const MAX_ERROR_SHORT_LEN = 60;
+const SHA256_LEN = 64;
+
+// ---------- Path resolvers (env-aware for hermetic testing) ----------
+
+function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function telemetryDir() {
+  return path.join(homeDir(), '.mindrian', 'telemetry', 'v1.13');
+}
+
+function telemetryFile() {
+  return path.join(telemetryDir(), 'mva.jsonl');
+}
+
+// ---------- Validation ----------
+
+/**
+ * validateEventPayload(event, payload) -> { ok: boolean, error?: string }
+ *
+ * Returns ok:false if:
+ *   - event is not in EVENT_TYPES
+ *   - any key in payload is not in ALLOWED_FIELDS[event]
+ *   - any string value violates the per-field length cap
+ *
+ * Numeric fields are not length-checked. The session_id field is added
+ * by emit() (not the caller), so it is not validated against ALLOWED_FIELDS.
+ */
+function validateEventPayload(event, payload) {
+  if (!EVENT_TYPES.includes(event)) {
+    return { ok: false, error: 'unknown_event' };
+  }
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, error: 'payload_not_object' };
+  }
+  const allowed = ALLOWED_FIELDS[event];
+  for (const key of Object.keys(payload)) {
+    if (!allowed.includes(key)) {
+      return { ok: false, error: 'unknown_field:' + key };
+    }
+    const v = payload[key];
+    if (typeof v === 'string') {
+      if (key === 'sentence_sha256') {
+        if (v.length !== SHA256_LEN) {
+          return { ok: false, error: 'sha256_length_invalid' };
+        }
+      } else if (key === 'error_short') {
+        if (v.length > MAX_ERROR_SHORT_LEN) {
+          return { ok: false, error: 'error_short_too_long' };
+        }
+      } else {
+        if (v.length > MAX_STRING_LEN) {
+          return { ok: false, error: 'string_too_long:' + key };
+        }
+      }
+    }
+  }
+  return { ok: true };
+}
+
+// ---------- Public emit() ----------
+
+/**
+ * emit(event, payload) -> appends one JSONL line to ~/.mindrian/telemetry/v1.13/mva.jsonl
+ *
+ * Validates first. On invalid payload throws a ValidationError (so callers
+ * cannot silently leak). On disk error returns silently (best-effort: the
+ * pipeline must not crash because telemetry is unavailable).
+ */
+function emit(event, payload) {
+  const v = validateEventPayload(event, payload);
+  if (!v.ok) {
+    const e = new Error('telemetry validation failed: ' + v.error);
+    e.code = 'TELEMETRY_VALIDATION';
+    throw e;
+  }
+
+  const record = Object.assign(
+    {
+      event: event,
+      timestamp: new Date().toISOString(),
+      session_id: (typeof process.env.CLAUDE_SESSION_ID === 'string' && process.env.CLAUDE_SESSION_ID.length > 0)
+        ? process.env.CLAUDE_SESSION_ID.slice(0, MAX_STRING_LEN)
+        : 'default'
+    },
+    payload
+  );
+
+  try {
+    fs.mkdirSync(telemetryDir(), { recursive: true });
+    fs.appendFileSync(telemetryFile(), JSON.stringify(record) + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort. The MVA pipeline must not fail because telemetry disk
+    // is unavailable. Plan 118-06's Dror harness checks for the file's
+    // existence post-run as the success signal.
+  }
+}
+
+module.exports = {
+  emit,
+  validateEventPayload,
+  EVENT_TYPES,
+  ALLOWED_FIELDS,
+  // Exposed for tests + downstream plans that need the canonical path
+  telemetryDir,
+  telemetryFile,
+};