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

package/lib/core/mva-telemetry.cjs

@@ -1,32 +1,9 @@
 /*
  * 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.
+ * Phase 121-01 -- mva-telemetry shim. Delegates to lib/core/telemetry/writer.cjs
+ * (the Canon Part 9 chokepoint), with a legacy dual-write to the historical
+ * ~/.mindrian/telemetry/v1.13/mva.jsonl path so existing readers keep working.
+ * TODO(v1.14.0): delete this shim; callers must import lib/core/telemetry/writer.cjs directly.
  */
 'use strict';
 
@@ -34,137 +11,48 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 
-// ---------- Frozen invariants ----------
+const writer = require('./telemetry/writer.cjs');
+const validator = require('./telemetry/validator.cjs');
+const schema = require('./telemetry/schema.cjs');
 
 const EVENT_TYPES = Object.freeze([
-  'mva_pipeline_started',
-  'mva_agent_returned',
-  'mva_brief_rendered',
-  'mva_option_selected',
-  'mva_brief_deployed',
-  'mva_pipeline_failed'
+  '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'])
+  mva_pipeline_started: schema.ALLOWED_FIELDS.mva_pipeline_started,
+  mva_agent_returned:   schema.ALLOWED_FIELDS.mva_agent_returned,
+  mva_brief_rendered:   schema.ALLOWED_FIELDS.mva_brief_rendered,
+  mva_option_selected:  schema.ALLOWED_FIELDS.mva_option_selected,
+  mva_brief_deployed:   schema.ALLOWED_FIELDS.mva_brief_deployed,
+  mva_pipeline_failed:  schema.ALLOWED_FIELDS.mva_pipeline_failed,
 });
 
-// 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() {
+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 };
+function _legacyMvaPath() {
+  return path.join(_homeDir(), '.mindrian', 'telemetry', 'v1.13', 'mva.jsonl');
 }
 
-// ---------- 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
-  );
-
+  writer.emit(event, payload); // Canon Part 8 gate + unified events-YYYY-WNN.jsonl append.
   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.
-  }
+    const sid = (typeof process.env.CLAUDE_SESSION_ID === 'string' && process.env.CLAUDE_SESSION_ID.length > 0)
+      ? process.env.CLAUDE_SESSION_ID.slice(0, schema.MAX_STRING_LEN) : 'default';
+    const record = Object.assign({ event: event, timestamp: new Date().toISOString(), session_id: sid }, payload);
+    fs.mkdirSync(path.dirname(_legacyMvaPath()), { recursive: true });
+    fs.appendFileSync(_legacyMvaPath(), JSON.stringify(record) + '\n', 'utf8');
+  } catch (_) { /* best-effort legacy dual-write */ }
 }
 
 module.exports = {
-  emit,
-  validateEventPayload,
-  EVENT_TYPES,
-  ALLOWED_FIELDS,
-  // Exposed for tests + downstream plans that need the canonical path
-  telemetryDir,
-  telemetryFile,
+  emit: emit,
+  validateEventPayload: validator.validateEventPayload,
+  EVENT_TYPES: EVENT_TYPES,
+  ALLOWED_FIELDS: ALLOWED_FIELDS,
+  telemetryDir: writer.telemetryDir,
+  telemetryFile: writer.telemetryFile,
 };

package/lib/core/navigation/edges.cjs

@@ -33,6 +33,41 @@ const ALLOWED_EDGE_TYPES = Object.freeze(new Set([
   // Phase 125 D7 -- F-selector decision edges (LOCKED LOCAL per Canon Part 8).
   'DEFERRED',
   'REJECTED',
+  // Phase 120-00 Wave 1 extension (Breakthrough Scan / Category G; D-18 HARD FLOOR enforcement
+  //   + D-20 Cypher-provable principle). DERIVED_FROM is the structural enforcement: a
+  //   Breakthrough node CANNOT surface without at least one DERIVED_FROM edge to an
+  //   Artifact node. Mirrors the Phase 125-00 DEFERRED + REJECTED additive idiom.
+  //
+  // Canon Part 4: every choice is graph data. The Breakthrough node + its DERIVED_FROM
+  //   edges are the graph-native artifact of pattern detection.
+  //
+  // Canon Part 8: writeEdge takes (db, params) over a LOCAL room.db handle; DERIVED_FROM
+  //   never crosses to Brain. Cross-room aggregation forbidden (Phase 8 cross-room fence).
+  //
+  // D-20 enforcement: lib/core/breakthrough/schema.cjs::writeBreakthrough wraps the
+  //   Breakthrough node insert + N DERIVED_FROM edge inserts in a single SQLite transaction.
+  //   If any step fails, the transaction rolls back -- partial Breakthrough state CANNOT
+  //   land. The Cypher invariant `MATCH (b:Breakthrough)-[:DERIVED_FROM]->(a:Artifact)
+  //   RETURN count(a)` is guaranteed >= 1 by construction.
+  'DERIVED_FROM',
+  // Phase 120-02 Wave 2 extension (Breakthrough Scan / Category G; D-09 file-as-decision
+  //   bridge). FILED_AS_DECISION is the typed edge that promotes a Breakthrough node into
+  //   the Phase 88 decision-log machinery when the user picks the [File as decision]
+  //   verb on F.7. Mirrors the Phase 120-00 DERIVED_FROM additive idiom verbatim.
+  //
+  // Canon Part 4: every choice is graph data. The Breakthrough -> Decision edge is the
+  //   graph-native bridge that lets future related breakthroughs reference the filed
+  //   decision via ENABLES edges (per CONTEXT.md D-15 "may be referenced as ENABLES in
+  //   future related breakthroughs").
+  //
+  // Canon Part 8: writeEdge takes (db, params) over a LOCAL room.db handle;
+  //   FILED_AS_DECISION never crosses to Brain. Cross-room aggregation forbidden.
+  //
+  // Emitted by: lib/core/breakthrough/verb-dispatch.cjs::handleFileAsDecision.
+  // The destination Decision node id is 'decision:' + breakthroughId by convention;
+  // Phase 88 decision-log machinery (or a future Phase 121 housekeeping pass) is
+  // responsible for materializing the Decision node body when one does not yet exist.
+  'FILED_AS_DECISION',
 ]));
 
 function isPlainObject(v) {

package/lib/core/navigation/memory-events.cjs

@@ -109,6 +109,132 @@ const EVENT_TYPES = Object.freeze(new Set([
   //   investment_level_at_decision}. NO cascade edge written (miss is temporal-only).
   //   Canon Part 8: user_intent stays LOCAL; never sent to Brain.
   'f_selector_miss',
+  // Phase 121.5-00 extension (SessionStart Coordinator: D-16 isolation + D-14 budget telemetry).
+  // Emitted by lib/sessionstart/contributor-isolator.cjs::runContributor on contributor failure
+  // and by scripts/sessionstart-coordinator.cjs::runAll on every coordinator pass.
+  //   sessionstart_contributor_failed -> a single contributor threw / validation-failed; coordinator
+  //                                      dropped it and continued. Payload: {contributor_id: <ladder id>,
+  //                                      error_class: <constructor name; enum-only>}. No stack, no
+  //                                      user content -- Canon Part 8 boundary preserved by the
+  //                                      isolator (stack lives in the LOCAL JSONL telemetry only).
+  //   sessionstart_coordinator_run    -> one envelope emitted; payload carries scalar counts
+  //                                      (fragments_total, fragments_compressed, fragments_dropped,
+  //                                      bytes_emitted). Scalars + enums only.
+  // Additive extension only; mirrors the Phase 110-02 / 116-00 / 117-00 / 124-02 / 125-01 / 125-06
+  // / 125-07 idiom verbatim. logEvent already rejects event_type values outside EVENT_TYPES.
+  'sessionstart_contributor_failed',
+  'sessionstart_coordinator_run',
+  // Phase 119-00 Wave 1 extension (Room-as-Receipt Invariant; D-01 + D-04 + D-06 telemetry mirror).
+  // Per CONTEXT.md Implementation Decisions D-01 + D-04 + D-06: the auto-create entrypoint
+  // (room_auto_created) fires synchronously inside scripts/auto-explore-fingerprint.cjs BEFORE
+  // the detached auto-explore-fire spawn so the spawned auto-explore output lands in a real
+  // room.db. The naming-decided + discarded events land in Plan 119-01.
+  //
+  // Additive extension; mirrors the Phase 124-02 2-string idiom and the Phase 117-00 6-string
+  // idiom. logEvent already rejects event_type values outside EVENT_TYPES -- so these are
+  // accepted only because they are now IN the Set. Set size grows by 3 (was 38 before Phase
+  // 119; now 41 baseline; coexists additively with any concurrent phase extension).
+  //
+  // Canon Part 9: SQL is the local mind; every choice is graph data. These three events are
+  // the canonical Part 10 sub-claim 3 ("rooms are receipts, not entry points") telemetry mirror.
+  'room_auto_created',
+  'room_naming_decided',
+  'room_discarded',
+  // Phase 119-01 Wave 2 extension (Room-as-Receipt Invariant; D-06 discard-cascade safety net).
+  // Per CONTEXT.md Architectural Decision item 4 (Claude's Discretion): the discard cascade
+  // is a SQLite transaction wrapping fs.rmSync + registry purge + memory_event emission.
+  // When the transaction fails partway (fs.rmSync raises EBUSY / EACCES, OR the registry
+  // purge fails non-atomically), the memory_event below lands so /mos:doctor can find
+  // orphaned rooms on next session-start.
+  //
+  // Additive extension only; mirrors the Plan 119-00 idiom verbatim. logEvent already
+  // rejects event_type values outside EVENT_TYPES -- so this is accepted only because
+  // it is now IN the Set. Set size grows by 1 (was 41 after Plan 119-00; now 42 baseline).
+  //
+  // Canon Part 9: SQL is the local mind; even partial failures become graph data so the
+  // recovery hook (/mos:doctor --orphaned-room-cleanup, deferred to v1.13.0 housekeeping)
+  // can scan + remediate.
+  'room_discard_partial_failure',
+  // Phase 120-00 Wave 1 extension (Breakthrough Scan / Category G; D-01..D-06 detector tier
+  // + D-09 file-as-decision bridge + D-10 mandatory dismiss + D-19 canary auto-throttle).
+  //
+  // Six strings; mirrors the Phase 119-00 3-string + 117-00 6-string + 124-02 2-string
+  // additive idiom. logEvent already rejects event_type values outside EVENT_TYPES -- so
+  // these are accepted only because they are now IN the Set. Set size grows by 6 (was 42
+  // baseline after Phase 119-01; now 48 baseline).
+  //
+  // Canon Part 10 sub-claim 5: variable reward fires automatically; the math IS the surface.
+  //   These six events are the canonical telemetry mirror for the breakthrough lifecycle:
+  //   soft-fire (buffer-only) -> hard-fire (surfaced) -> user response (confirm/dismiss/file)
+  //   -> canary auto-throttle (D-19 30%-over-100-fire-window static threshold).
+  //
+  // Canon Part 4: every choice is graph data. The breakthrough_filed_as_decision event is
+  //   the bridge to Phase 88 decision-log machinery -- promotes a breakthrough to a
+  //   first-class decision with audit trail.
+  //
+  // Canon Part 8: payloads carry scalar enums + framework names + sha256 hashes only;
+  //   theme strings are sanitized at write time per the Phase 90-06 sanitizeDetailScalar
+  //   precedent. Raw artifact content never lands in a memory_event.
+  'breakthrough_detected_soft',
+  'breakthrough_surfaced',
+  'breakthrough_confirmed',
+  'breakthrough_dismissed',
+  'breakthrough_filed_as_decision',
+  'breakthrough_throttled',
+  // Phase 120-02 Wave 2 additive extension (D-20 third structural enforcement
+  //   point: surfaceBreakthrough refuses provenance-less Breakthrough nodes at
+  //   surface time and emits this event for /mos:doctor traceability). Mirrors
+  //   the Phase 120-00 6-string additive idiom verbatim. logEvent already
+  //   rejects event_type values outside EVENT_TYPES -- so this is accepted only
+  //   because it is now IN the Set. Set size grows additively by 1.
+  //
+  // Canon Part 4: every choice is graph data -- the refusal itself is a typed
+  //   signal that an upstream caller attempted to bypass the D-20 invariant.
+  // Canon Part 8: pure LOCAL telemetry; no Brain coupling; payload carries
+  //   breakthrough_id + reason scalars only.
+  'breakthrough_surface_blocked',
+  // Phase 120-03 Wave 2 additive extension (D-18 SOFT_BAND review queue telemetry
+  //   mirror). Mirrors the Phase 120-02 1-string + Phase 120-00 6-string + 117-00
+  //   6-string + 124-02 2-string additive idiom verbatim. logEvent already rejects
+  //   event_type values outside EVENT_TYPES -- so this is accepted only because it
+  //   is now IN the Set. Set size grows additively by 1.
+  //
+  // Canon Part 4: every choice is graph data; the SOFT_BAND review queue is the
+  //   typed graph signal for D-18 mid-confidence candidates that the system queues
+  //   for manual sample-20% weekly review (becomes retraining data per CONTEXT.md).
+  // Canon Part 8: payload carries scalar enums (kind), numeric confidence, and the
+  //   queue_id handle; no raw artifact content lands in this event.
+  // Canon Part 9: ALL writes via navigation.cjs::logMemoryEvent chokepoint.
+  'breakthrough_in_review_queue',
+  // 260517-dcw dogfood-bridge extension (Canon Part 6 Product-as-Venture; D-04
+  //   dog-fooding mandate telemetry mirror). Six strings; mirrors the Phase 120-00
+  //   6-string + 117-00 6-string + 124-02 2-string + 110-02 3-string additive idiom.
+  //   logEvent already rejects event_type values outside EVENT_TYPES -- so these are
+  //   accepted only because they are now IN the Set. Set size grows by 6 (was 48
+  //   baseline after Phase 120-00; now 54 baseline).
+  //
+  // Canon Part 9 binding: SQL is the local mind; the plugin's own development
+  //   activity becomes graph data in the plugin's own venture room. Every Edit/
+  //   Write/MultiEdit on the plugin repo that matches the dog-food filter is a
+  //   file_changed event in ~/MindrianRooms/mindrian/room.db.
+  //
+  // Canon Part 8 binding: payloads carry the absolute path string (LOCAL data,
+  //   already on the local box; never sent to Brain), the tool name (enum scalar:
+  //   Edit / Write / MultiEdit), and the ISO timestamp. Zero user-content egress.
+  //
+  // Active emit site: scripts/dogfood-emit.cjs (file_changed only in this plan).
+  // Stub event types (no callers yet; reserved for future triggers per task_scope):
+  //   commit_landed       -> a git post-commit hook (future)
+  //   phase_completed     -> /gsd:phase-complete (future)
+  //   release_shipped     -> scripts/release.sh post-publish (future)
+  //   tester_signal       -> tester reply ingestion (future)
+  //   decision_captured   -> /mos:decide F.1 selector (future)
+  'file_changed',
+  'commit_landed',
+  'phase_completed',
+  'release_shipped',
+  'tester_signal',
+  'decision_captured',
 ]));
 
 function isPlainObject(v) {