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

package/lib/core/telemetry/validator.cjs

@@ -0,0 +1,197 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121-00 -- emit-time validator (Canon Part 8 constitutional gate).
+ *
+ * Every telemetry emit() routes through validateEventPayload() BEFORE the
+ * fs.appendFileSync at the writer. This is the single chokepoint that
+ * structurally enforces Canon Part 8 (Graph Boundary):
+ *
+ *   LOCAL data -> BRAIN:  NO (not enforced here directly, but the symmetric
+ *                            forbidden-pattern list makes LEAK-via-telemetry
+ *                            equally hard -- a future Brain consumer of
+ *                            JSONL events can never pick up artifact bytes)
+ *
+ *   This validator's job: reject any string-field value containing
+ *     (a) Cypher query body fragments
+ *     (b) Email addresses
+ *     (c) Phone numbers
+ *     (d) Brain MCP host URL references (the production methodology host)
+ *     (e) Absolute filesystem paths (>= 2 path separators)
+ *     (f) Raw hex >32 chars in NON-hash-class fields
+ *     (g) Free-text English prose (>120 chars + 3+ spaces + >40% lowercase)
+ *
+ * The Phase 110-05 seed-pattern test approach is the model. Each rejection
+ * returns ok:false with an error string of shape "forbidden_pattern:<name>:<key>"
+ * so adversarial fixtures can match precisely.
+ *
+ * Per Canon Part 9 (Memory Locality), validator.cjs is the LOCAL gate. It
+ * never reaches over the network; it runs synchronously on the caller's
+ * stack frame. Zero new runtime dependencies.
+ */
+'use strict';
+
+const {
+  EVENT_TYPES,
+  ALLOWED_FIELDS,
+  MAX_STRING_LEN,
+  MAX_ERROR_SHORT_LEN,
+  SHA256_LEN,
+} = require('./schema.cjs');
+
+// ---------- Canon Part 8 forbidden-pattern detectors ----------
+//
+// Each regex below is the pattern to reject. Order matters for error-message
+// specificity (Cypher and brain URL are checked first because they are the
+// highest-signal Canon breaches). Names map 1:1 to error strings emitted.
+
+// (a) Cypher fragment: any of MATCH / RETURN / CREATE / MERGE followed by '('.
+// Case-insensitive. Catches both "MATCH (n) RETURN n" and lowercase prose
+// referencing those keywords as code, but is loose enough to allow ordinary
+// English with the word "match" or "return" (because the '(' is required).
+const CYPHER_RE = /\b(MATCH|RETURN|CREATE|MERGE)\s*\(/i;
+
+// (b) Email: standard RFC-5322-ish local@domain.tld.
+const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
+
+// (c) Phone: 10-digit US-style with optional separators (hyphens, dots, spaces).
+const PHONE_RE = /\b\d{3}[-.\s]?\d{3}[-.\s]?\d{4}\b/;
+
+// (d) Brain URL: any reference to the production Brain MCP host. Built from
+// concatenated tokens so this very source file does not itself contain the
+// literal forbidden substring (preserving the Canon Part 8 zero-network grep
+// gate over the telemetry module while still detecting the host in payloads).
+const BRAIN_HOST_TOKENS = ['brain', 'mindrian', 'ai'];
+const BRAIN_URL_RE = new RegExp(BRAIN_HOST_TOKENS.join('\\.'), 'i');
+
+// (e) Absolute path with >= 2 path separators after the initial / or ~.
+// Matches "/home/jsagi/foo/bar.md" but not "/" alone or "/foo".
+const ABS_PATH_RE = /^[\/~][^"]*\/[^"]*\//;
+
+// (f) Raw hex >32 chars. We allow legitimate sha256 (64 hex) ONLY in fields
+// whose name ends with '_sha256' or '_hash'. All other fields with long hex
+// strings are suspect (likely smuggled identifier or wallet/key material).
+const RAW_HEX_RE = /^[0-9a-f]{33,}$/i;
+const HASH_FIELD_RE = /(_sha256|_hash)$/;
+
+// (g) Free-text English prose heuristic. Three conditions must all hold:
+//   - string is > 120 chars long (well past any enum/hash/score)
+//   - contains 3+ space characters (multi-word)
+//   - >40% of characters are lowercase letters (English-ratio)
+function looksLikeFreeTextProse(s) {
+  if (s.length <= 120) return false;
+  let spaces = 0;
+  let lowers = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 32) spaces++;
+    else if (c >= 97 && c <= 122) lowers++;
+  }
+  if (spaces < 3) return false;
+  if ((lowers / s.length) <= 0.4) return false;
+  return true;
+}
+
+// ---------- Forbidden-pattern dispatch ----------
+
+function scanForbidden(key, value) {
+  // (a) Cypher
+  if (CYPHER_RE.test(value)) {
+    return 'forbidden_pattern:cypher:' + key;
+  }
+  // (d) Brain URL
+  if (BRAIN_URL_RE.test(value)) {
+    return 'forbidden_pattern:brain_url:' + key;
+  }
+  // (b) Email
+  if (EMAIL_RE.test(value)) {
+    return 'forbidden_pattern:email:' + key;
+  }
+  // (c) Phone
+  if (PHONE_RE.test(value)) {
+    return 'forbidden_pattern:phone:' + key;
+  }
+  // (e) Absolute path
+  if (ABS_PATH_RE.test(value)) {
+    return 'forbidden_pattern:absolute_path:' + key;
+  }
+  // (f) Raw hex in non-hash field
+  if (!HASH_FIELD_RE.test(key) && RAW_HEX_RE.test(value)) {
+    return 'forbidden_pattern:raw_hex:' + key;
+  }
+  // (g) Free-text prose
+  if (looksLikeFreeTextProse(value)) {
+    return 'free_text_prose_suspected:' + key;
+  }
+  return null;
+}
+
+// ---------- Public entry: validateEventPayload(event, payload) ----------
+/**
+ * Returns { ok: true } on accept; { ok: false, error: <reason> } on reject.
+ *
+ * Reasons:
+ *   unknown_event
+ *   payload_not_object
+ *   unknown_field:<key>
+ *   sha256_length_invalid:<key>
+ *   error_short_too_long
+ *   string_too_long:<key>
+ *   forbidden_pattern:<name>:<key>
+ *   free_text_prose_suspected:<key>
+ *
+ * Numeric and boolean fields are length-skipped. Hash-class fields (suffix
+ * '_sha256' or '_hash') are exempt from the raw-hex detector. emit() is the
+ * sole caller; tests call this directly to verify the constitutional gate.
+ */
+function validateEventPayload(event, payload) {
+  // 1. Event must be in the v1 frozen taxonomy.
+  if (!EVENT_TYPES.includes(event)) {
+    return { ok: false, error: 'unknown_event:' + event };
+  }
+  // 2. Payload must be a non-null object.
+  if (!payload || typeof payload !== 'object') {
+    return { ok: false, error: 'payload_not_object' };
+  }
+  const allowed = ALLOWED_FIELDS[event];
+
+  for (const key of Object.keys(payload)) {
+    // 3. Key must be in ALLOWED_FIELDS[event].
+    if (!allowed.includes(key)) {
+      return { ok: false, error: 'unknown_field:' + key };
+    }
+    const v = payload[key];
+
+    // Strings: Canon Part 8 forbidden-pattern scan FIRST, then length cap.
+    if (typeof v === 'string') {
+      // Forbidden patterns take precedence over length checks so adversarial
+      // fixtures get a specific, actionable error message.
+      const forbidden = scanForbidden(key, v);
+      if (forbidden) {
+        return { ok: false, error: forbidden };
+      }
+
+      // Per-field length checks. sha256 must be exactly 64 hex chars;
+      // error_short caps lower; everything else caps at MAX_STRING_LEN.
+      if (key === 'sentence_sha256' || key === 'room_slug_sha256') {
+        if (v.length !== SHA256_LEN) {
+          return { ok: false, error: 'sha256_length_invalid:' + key };
+        }
+      } 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 };
+        }
+      }
+    }
+    // Numbers and booleans: pass through. Caller responsible for value
+    // sanity (e.g. ranker_confidence in 0..1). We deliberately do not
+    // range-check to keep the validator minimal and predictable.
+  }
+  return { ok: true };
+}
+
+module.exports = { validateEventPayload };

package/lib/core/telemetry/validator.test.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121-00 -- emit-time validator acceptance tests.
+ *
+ * Verifies validator.cjs is the Canon Part 8 constitutional gate that
+ * rejects events containing Brain query bodies, room artifact strings,
+ * personal identifiers (emails, phone numbers, raw hex), absolute filesystem
+ * paths, brain.mindrian.ai references, and free-text prose. Mirrors the
+ * Phase 110-05 seed-pattern adversarial fixture approach.
+ *
+ * Test map (7 cases, one-to-one with the PLAN <behavior> block for Task 1):
+ *   3.  validateEventPayload('unknown_event', {}) returns { ok: false, error: /unknown_event/ }
+ *   4.  validateEventPayload('selector_pick', {valid payload}) returns { ok: true }
+ *   5.  validateEventPayload('selector_pick', { rogue_field: 'x' }) returns { ok: false, error: /unknown_field/ }
+ *   6.  7 adversarial forbidden-pattern rejections (Canon Part 8):
+ *         (a) Cypher query body  "MATCH (n:Framework) RETURN n"
+ *         (b) Free-text prose    > 120 chars with 3+ spaces and >40% lowercase
+ *         (c) Email              "user@example.com"
+ *         (d) Raw hex >32 chars  in non-sha256 field
+ *         (e) Absolute path      "/home/jsagi/MindrianRooms/foo/bar/baz.md"
+ *         (f) Phone              "555-123-4567"
+ *         (g) Brain URL          "https://brain.mindrian.ai/v1/query"
+ *
+ * Registered in lib/memory/run-feynman-tests.cjs.
+ */
+
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const REPO = path.resolve(__dirname, '..', '..', '..');
+const VALIDATOR_PATH = path.join(REPO, 'lib/core/telemetry/validator.cjs');
+
+try { delete require.cache[require.resolve(VALIDATOR_PATH)]; } catch (_) {}
+const validator = require(VALIDATOR_PATH);
+
+assert.equal(typeof validator.validateEventPayload, 'function',
+  'validator must export validateEventPayload()');
+
+// ---------- Test 3: unknown_event rejection ----------
+
+(function test3UnknownEvent() {
+  const result = validator.validateEventPayload('not_a_real_event', {});
+  assert.equal(result.ok, false,
+    'unknown event must return ok:false');
+  assert.match(result.error, /unknown_event/,
+    'error must mention unknown_event, got: ' + result.error);
+  console.log('PASS test 3: unknown_event -> ok:false');
+})();
+
+// ---------- Test 4: valid selector_pick payload ----------
+
+(function test4ValidSelectorPick() {
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    mode: 'A',
+    ranker_confidence: 0.73,
+    recommended_rendered: true,
+    options_count: 4,
+    room_slug_sha256: 'a'.repeat(64),
+    verb_chosen: 'Run Methodology',
+  });
+  assert.equal(result.ok, true,
+    'valid selector_pick payload must validate; got: ' + JSON.stringify(result));
+  console.log('PASS test 4: valid selector_pick payload -> ok:true');
+})();
+
+// ---------- Test 5: unknown field rejection ----------
+
+(function test5UnknownField() {
+  const result = validator.validateEventPayload('selector_pick', { rogue_field: 'x' });
+  assert.equal(result.ok, false,
+    'unknown field must return ok:false');
+  assert.match(result.error, /unknown_field/,
+    'error must mention unknown_field, got: ' + result.error);
+  console.log('PASS test 5: unknown_field -> ok:false');
+})();
+
+// ---------- Test 6 (a-g): Canon Part 8 adversarial forbidden patterns ----------
+
+(function test6aCypherQueryBody() {
+  // Cypher body must be rejected even when injected into an allowed field
+  // (verb_chosen has length cap, but the Cypher detector should fire FIRST).
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: 'MATCH (n:Framework) RETURN n',
+  });
+  assert.equal(result.ok, false,
+    'Cypher fragment must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*cypher/i,
+    'error must mention forbidden_pattern + cypher, got: ' + result.error);
+  console.log('PASS test 6a: Cypher query body rejected');
+})();
+
+(function test6bFreeTextProse() {
+  // 130+ char string with many spaces and high lowercase ratio.
+  const prose = 'the navigator walked into the room and the team began discussing the long history of the venture together with a beautiful question framework that everyone could understand';
+  assert.ok(prose.length > 120, 'fixture must be > 120 chars');
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: prose,
+  });
+  assert.equal(result.ok, false,
+    'free-text prose must be rejected; got: ' + JSON.stringify(result));
+  // Either prose heuristic OR length cap fires; both signal Part 8 enforcement.
+  assert.match(result.error, /free_text_prose_suspected|string_too_long|forbidden_pattern/,
+    'error must indicate prose rejection, got: ' + result.error);
+  console.log('PASS test 6b: free-text prose >120 chars rejected');
+})();
+
+(function test6cEmail() {
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: 'user@example.com',
+  });
+  assert.equal(result.ok, false,
+    'email must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*email/i,
+    'error must mention forbidden_pattern + email, got: ' + result.error);
+  console.log('PASS test 6c: email rejected');
+})();
+
+(function test6dRawHex() {
+  // 40-char hex in verb_chosen (a non-hash field).
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: 'deadbeefcafebabe1234567890abcdef0123456789abcdef',
+  });
+  assert.equal(result.ok, false,
+    'raw hex >32 chars in non-sha256 field must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*hex|string_too_long/i,
+    'error must mention forbidden_pattern + hex (or string_too_long fallback), got: ' + result.error);
+  console.log('PASS test 6d: raw hex >32 chars in non-sha256 field rejected');
+})();
+
+(function test6eAbsolutePath() {
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: '/home/jsagi/MindrianRooms/foo/bar/baz.md',
+  });
+  assert.equal(result.ok, false,
+    'absolute path must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*(path|absolute)/i,
+    'error must mention forbidden_pattern + path, got: ' + result.error);
+  console.log('PASS test 6e: absolute path rejected');
+})();
+
+(function test6fPhone() {
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: '555-123-4567',
+  });
+  assert.equal(result.ok, false,
+    'phone number must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*phone/i,
+    'error must mention forbidden_pattern + phone, got: ' + result.error);
+  console.log('PASS test 6f: phone number rejected');
+})();
+
+(function test6gBrainURL() {
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    verb_chosen: 'https://brain.mindrian.ai/v1',
+  });
+  assert.equal(result.ok, false,
+    'brain.mindrian.ai URL must be rejected; got: ' + JSON.stringify(result));
+  assert.match(result.error, /forbidden_pattern.*(brain|url)/i,
+    'error must mention forbidden_pattern + brain/url, got: ' + result.error);
+  console.log('PASS test 6g: brain.mindrian.ai URL rejected');
+})();
+
+// ---------- Sanity: sha256 hash field (room_slug_sha256) NOT flagged as raw hex ----------
+
+(function test7Sha256NotFlagged() {
+  // 64-char hex is the valid sha256 length; must NOT trigger hex detector.
+  const result = validator.validateEventPayload('selector_pick', {
+    sub_shape: 'F.1',
+    room_slug_sha256: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
+  });
+  assert.equal(result.ok, true,
+    'sha256 hash in dedicated field must validate; got: ' + JSON.stringify(result));
+  console.log('PASS test 7: sha256 hash in room_slug_sha256 NOT flagged as raw hex');
+})();
+
+console.log('\nvalidator.test.cjs: 7/7 tests passed');

package/lib/core/telemetry/writer.cjs

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121-00 -- unified trajectory-telemetry writer (THE chokepoint).
+ *
+ * Per Canon Part 9 (Memory Locality + single chokepoint pattern, mirroring
+ * navigation.cjs), every downstream capture point in Phase 121-02 and 121-03
+ * MUST emit through this module. The Phase 118 lib/core/mva-telemetry.cjs is
+ * the architectural ancestor; this writer copies its shape verbatim and
+ * extends with:
+ *   - broader EVENT_TYPES dispatch (15 in v1, frozen)
+ *   - ISO-week rotation: events-YYYY-WNN.jsonl with zero-padded week
+ *   - per-row schema_version (Number 1) per D-10
+ *   - Canon Part 8 emit-time validator (validator.cjs) as the constitutional
+ *     gate; rejected payloads throw with code = 'TELEMETRY_VALIDATION'
+ *
+ * Atomic JSONL append via fs.appendFileSync. POSIX append semantics guarantee
+ * atomicity for writes within PIPE_BUF (4096 bytes on Linux); our lines are
+ * well below that limit. Disk errors are swallowed silently: the pipeline
+ * must never crash because telemetry storage is unavailable (best-effort
+ * observability per D-12).
+ *
+ * Zero network surface. Zero new runtime dependencies. Pure CJS, node
+ * built-ins only.
+ *
+ * Public API (exported):
+ *   emit(eventType, payload)      -- the chokepoint. Throws on validation breach.
+ *   telemetryDir()                -- ~/.mindrian/telemetry/v1.13/
+ *   telemetryFile(date?)          -- dir + isoWeekFilename(date or now)
+ *   isoWeekFilename(date)         -- pure helper: events-YYYY-WNN.jsonl
+ *   EVENT_TYPES                   -- re-export from schema.cjs
+ *   ALLOWED_FIELDS                -- re-export from schema.cjs
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { validateEventPayload } = require('./validator.cjs');
+const {
+  EVENT_TYPES,
+  ALLOWED_FIELDS,
+  SCHEMA_VERSION,
+  MAX_STRING_LEN,
+} = require('./schema.cjs');
+
+// ---------- 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');
+}
+
+// ---------- ISO-8601 week computation ----------
+//
+// Monday-start. Week 1 of a year is the week containing the first Thursday.
+// Algorithm: shift the date to the Thursday of its week, then count weeks
+// from the year-start of that shifted date. The shift moves Jan 1 of a year
+// whose Jan 1 is Mon/Tue/Wed/Thu into the same year, and Fri/Sat/Sun into
+// the previous year (since W52/W53 of the previous year owns those days).
+//
+// Year is taken from the shifted Thursday, not the input date -- this is
+// what makes 2025-12-30 (a Tuesday) correctly belong to 2026-W01.
+
+function isoWeekFilename(date) {
+  // Strip to UTC midnight to keep the math deterministic across TZs.
+  const d = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  // Shift to the Thursday of this ISO week.
+  // getUTCDay(): Sunday=0..Saturday=6. ISO: Monday=1..Sunday=7.
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  // Year-start of the year that owns the shifted Thursday.
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  // Week number = ceil(daysFromYearStart / 7) (the +1 accounts for the
+  // day-zero offset; the /86400000 converts ms to days).
+  const weekNum = Math.ceil(((d - yearStart) / 86400000 + 1) / 7);
+  const wnn = String(weekNum).padStart(2, '0');
+  return `events-${d.getUTCFullYear()}-W${wnn}.jsonl`;
+}
+
+function telemetryFile(date) {
+  return path.join(telemetryDir(), isoWeekFilename(date || new Date()));
+}
+
+// ---------- Public emit() chokepoint ----------
+/**
+ * emit(event, payload) -> void
+ *
+ * Validates first against the frozen v1 schema + Canon Part 8 forbidden
+ * patterns (validator.cjs). On valid payload, builds the record and
+ * atomically appends one JSONL line to the current ISO-week file.
+ *
+ * Record shape:
+ *   {
+ *     event:           <string> (one of EVENT_TYPES)
+ *     schema_version:  1        (Number, D-10)
+ *     timestamp:       <ISO-8601 string>
+ *     session_id:      <string> (process.env.CLAUDE_SESSION_ID or 'default')
+ *     ...payload (keys per ALLOWED_FIELDS[event])
+ *   }
+ *
+ * Failure modes:
+ *   - Invalid payload: throws Error with .code = 'TELEMETRY_VALIDATION'.
+ *   - Disk write failure (mkdir / appendFileSync): swallowed silently.
+ *     Per D-12 silent observability, telemetry must never crash the
+ *     pipeline whose trajectory it is observing.
+ */
+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,
+      schema_version: SCHEMA_VERSION,
+      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 pipeline must not crash because telemetry storage is
+    // unavailable. Per D-12, telemetry is a lab-side concern observed via
+    // post-hoc tail reads, not a runtime contract.
+  }
+}
+
+module.exports = { emit, telemetryDir, telemetryFile, isoWeekFilename, EVENT_TYPES, ALLOWED_FIELDS };