@mindrian_os/install 1.13.0-beta.11

package/lib/memory/pending-tension-store.cjs

@@ -0,0 +1,373 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 116-01 Wave 1 -- pending-tension-store substrate.
+ *
+ * JSONL append-only state store at ~/.mindrian/pending-tensions/<roomSlug>.jsonl.
+ * Per CONTEXT.md D-07, D-07a, D-07b: JSONL is the decay state machine ground
+ * truth; workspace-guard-clean (OUTSIDE plugin repo via os.homedir()); no user
+ * content fields per Canon Part 8.
+ *
+ * Graph-native HARD RULE (memory feedback_reverse_salient_agent_graph_native):
+ *   1. Reads route through lib/core/navigation.cjs only -- the Phase 109 D-06
+ *      chokepoint is preserved (no direct DB module imports here).
+ *   2. Brain MCP is OUT of this module's surface area -- Canon Part 8 boundary
+ *      is preserved (zero outbound network surface, zero remote-graph imports).
+ *   3. Telemetry side-channels via stdout / stderr are OUT of this module per
+ *      RESEARCH Section 13.9 -- the SessionStart hook owns the stdout envelope.
+ *
+ * Pattern: append-only writer + LWW replay (RESEARCH Section 6.4).
+ *   - Each tension is represented by its LATEST entry in the JSONL.
+ *   - State changes are recorded as NEW entries with the same tension_id.
+ *   - Reader plays the JSONL forward and keeps only the most-recent entry
+ *     per tension_id (last-write-wins on replay).
+ *
+ * Concurrency: appendFileSync is POSIX-atomic for lines smaller than PIPE_BUF
+ * (typically 4096 bytes; tension entries are well under per RESEARCH 6.5).
+ *
+ * Pure CJS, node built-ins only, zero new runtime dependencies.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+// ---------- Constants ----------
+
+const PENDING_TENSIONS_DIR = path.join(os.homedir(), '.mindrian', 'pending-tensions');
+const VALID_STATES = Object.freeze(new Set(['queued', 'surfaced', 'resolved', 'dropped']));
+const VALID_TYPES = Object.freeze(new Set([
+  'contradiction',
+  'convergence',
+  'stale_decision',
+  'open_question',
+]));
+const VALID_RESPONSES = Object.freeze(new Set(['RESOLVE', 'LATER', 'SKIP', 'DROPPED']));
+const TENSION_ID_LEN = 32;
+
+// User-content key denylist (Canon Part 8 -- artifact bodies live in the graph,
+// never in this JSONL). Rejection is fail-fast at appendTension time so a
+// caller bug never leaks user content to disk in the canonical state file.
+const USER_CONTENT_KEY_DENYLIST = Object.freeze([
+  'body_text',
+  'source_title',
+  'target_title',
+  'quoted_text',
+  'artifact_body',
+]);
+
+// ---------- Tension id (deterministic, idempotent) ----------
+
+/**
+ * Compute the deterministic tension id for a (source, target, type) tuple.
+ * Order-sensitive per RESEARCH Section 4.3 -- swapping source and target
+ * yields a distinct id (so a contradiction edge and its reverse are
+ * tracked separately if both ever land in the graph).
+ *
+ * @param {string} sourceNodeId
+ * @param {string} targetNodeId
+ * @param {string} tensionType  one of VALID_TYPES
+ * @returns {string} 32-char hex sha256 prefix
+ */
+function computeTensionId(sourceNodeId, targetNodeId, tensionType) {
+  const basis = String(sourceNodeId) + '|' + String(targetNodeId) + '|' + String(tensionType);
+  return crypto.createHash('sha256').update(basis).digest('hex').slice(0, TENSION_ID_LEN);
+}
+
+// ---------- JSONL path resolution (workspace-guard-clean) ----------
+
+/**
+ * Resolve the JSONL path for a given room slug. Always returns a path under
+ * os.homedir() per D-07b (OUTSIDE the plugin repo).
+ *
+ * @param {string} roomSlug
+ * @returns {string} absolute path
+ */
+function jsonlPath(roomSlug) {
+  const safeSlug = encodeURIComponent(String(roomSlug || 'default-room'));
+  return path.join(PENDING_TENSIONS_DIR, safeSlug + '.jsonl');
+}
+
+// ---------- Internal helpers ----------
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isHex32(v) {
+  return typeof v === 'string' && /^[0-9a-f]{32}$/.test(v);
+}
+
+function violatesUserContentBoundary(entry) {
+  for (const k of USER_CONTENT_KEY_DENYLIST) {
+    if (Object.prototype.hasOwnProperty.call(entry, k)) return k;
+  }
+  // context_signature is allowed but its sub-fields must also be enum-only.
+  if (isPlainObject(entry.context_signature)) {
+    for (const k of USER_CONTENT_KEY_DENYLIST) {
+      if (Object.prototype.hasOwnProperty.call(entry.context_signature, k)) return 'context_signature.' + k;
+    }
+  }
+  return null;
+}
+
+function validateEntryShape(entry) {
+  if (!isPlainObject(entry)) return 'entry_not_object';
+  if (!isHex32(entry.tension_id)) return 'invalid_tension_id';
+  if (!VALID_TYPES.has(entry.type)) return 'invalid_type';
+  if (!VALID_STATES.has(entry.state)) return 'invalid_state';
+  if (!Number.isInteger(entry.surfacing_count) || entry.surfacing_count < 0) {
+    return 'invalid_surfacing_count';
+  }
+  return null;
+}
+
+// ---------- Public API ----------
+
+/**
+ * Append a tension entry to the room's JSONL file. Creates the directory if
+ * missing. Validates shape + Canon Part 8 boundary; rejects user-content
+ * fields.
+ *
+ * @param {string} roomSlug
+ * @param {object} entry  conforming to D-07 schema
+ * @returns {{ok:true, path:string} | {ok:false, reason:string}}
+ */
+function appendTension(roomSlug, entry) {
+  if (!isPlainObject(entry)) {
+    return { ok: false, reason: 'entry_not_object' };
+  }
+  const violator = violatesUserContentBoundary(entry);
+  if (violator) {
+    return { ok: false, reason: 'canon_part_8_violation:' + violator };
+  }
+  const shapeErr = validateEntryShape(entry);
+  if (shapeErr) {
+    return { ok: false, reason: shapeErr };
+  }
+  try {
+    fs.mkdirSync(PENDING_TENSIONS_DIR, { recursive: true });
+    const file = jsonlPath(roomSlug);
+    fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+    return { ok: true, path: file };
+  } catch (err) {
+    const msg = (err && err.message) ? String(err.message) : 'append_failed';
+    return { ok: false, reason: msg.slice(0, 80) };
+  }
+}
+
+/**
+ * Read all tensions for a room, applying LWW replay (last entry per
+ * tension_id wins). Returns [] when the file is missing. Tolerates corrupt
+ * lines by skipping them silently.
+ *
+ * @param {string} roomSlug
+ * @returns {Array<object>}
+ */
+function readTensions(roomSlug) {
+  const file = jsonlPath(roomSlug);
+  if (!fs.existsSync(file)) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (_e) {
+    return [];
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  const byId = new Map();
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (_e) {
+      continue; // corrupt line tolerated
+    }
+    if (!isPlainObject(entry) || !isHex32(entry.tension_id)) continue;
+    byId.set(entry.tension_id, entry);
+  }
+  return Array.from(byId.values());
+}
+
+/**
+ * Find the latest entry for a single tension_id. Returns null when missing.
+ * Internal helper for the state-transition functions.
+ */
+function findLatest(roomSlug, tension_id) {
+  if (!isHex32(tension_id)) return null;
+  const all = readTensions(roomSlug);
+  for (const e of all) {
+    if (e.tension_id === tension_id) return e;
+  }
+  return null;
+}
+
+/**
+ * Mark a tension as surfaced -- increments surfacing_count and sets
+ * last_surfaced_at to now. State transitions to 'surfaced'.
+ */
+function markSurfaced(roomSlug, tension_id) {
+  const prev = findLatest(roomSlug, tension_id);
+  if (!prev) return { ok: false, reason: 'tension_not_found' };
+  const next = Object.assign({}, prev, {
+    state: 'surfaced',
+    surfacing_count: (Number.isInteger(prev.surfacing_count) ? prev.surfacing_count : 0) + 1,
+    last_surfaced_at: Date.now(),
+  });
+  const r = appendTension(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true, surfacing_count: next.surfacing_count };
+}
+
+/**
+ * Mark a tension as resolved with a user response. State -> 'resolved'.
+ *
+ * @param {string} roomSlug
+ * @param {string} tension_id
+ * @param {string} response  one of VALID_RESPONSES (RESOLVE / LATER / SKIP / DROPPED)
+ */
+function markResolved(roomSlug, tension_id, response) {
+  if (!VALID_RESPONSES.has(response)) {
+    return { ok: false, reason: 'invalid_response' };
+  }
+  const prev = findLatest(roomSlug, tension_id);
+  if (!prev) return { ok: false, reason: 'tension_not_found' };
+  const next = Object.assign({}, prev, {
+    state: 'resolved',
+    last_response: response,
+  });
+  const r = appendTension(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true };
+}
+
+/**
+ * Mark a tension as dropped (3-strikes decay or explicit drop). Terminal.
+ */
+function markDropped(roomSlug, tension_id) {
+  const prev = findLatest(roomSlug, tension_id);
+  if (!prev) return { ok: false, reason: 'tension_not_found' };
+  const next = Object.assign({}, prev, {
+    state: 'dropped',
+    last_response: 'DROPPED',
+  });
+  const r = appendTension(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true };
+}
+
+/**
+ * Re-queue a tension after the user picked LATER. State -> 'queued'.
+ * Per RESEARCH Section 11.2: surfacing_count is NOT decremented (LATER does
+ * not reset the 3-strikes budget).
+ */
+function requeue(roomSlug, tension_id) {
+  const prev = findLatest(roomSlug, tension_id);
+  if (!prev) return { ok: false, reason: 'tension_not_found' };
+  const next = Object.assign({}, prev, {
+    state: 'queued',
+  });
+  const r = appendTension(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true };
+}
+
+/**
+ * Phase 116-03 Wave 3: pre-pass that scans JSONL state and writes 'dropped'
+ * transitions for tensions where surfacing_count >= 3 AND state IN
+ * ('queued', 'surfaced'). Implements the D-03 / D-03a 3-strikes rule.
+ *
+ * Idempotent: re-running on already-dropped tensions writes no new transitions
+ * because the terminal-state filter excludes 'resolved' and 'dropped' from the
+ * scan (per RESEARCH Section 11.2 rows 8 and 9).
+ *
+ * Boundary case (CONTEXT.md D-03a): if surfacing_count == 3 AND user picks
+ * RESOLVE before this pre-pass runs, state is already 'resolved' (terminal)
+ * and evaluateAndDecay leaves it alone. The 3-strikes rule only fires AFTER
+ * 3 surfacings WITHOUT resolution.
+ *
+ * Cross-session durable: reads via readTensions which is JSONL LWW replay
+ * (RESEARCH Section 6.4) so this pre-pass evaluates the LATEST state per
+ * tension_id regardless of how many sessions wrote between now and the
+ * first append.
+ *
+ * Sync. Never throws. On any error returns { droppedTensionIds: [],
+ * evaluatedCount: 0 } so the SessionStart hook can never be derailed by a
+ * decay-evaluation failure.
+ *
+ * @param {string} roomSlug
+ * @returns {{droppedTensionIds: string[], evaluatedCount: number}}
+ */
+function evaluateAndDecay(roomSlug) {
+  try {
+    const tensions = readTensions(roomSlug);
+    const droppedTensionIds = [];
+    for (const t of tensions) {
+      if (!isPlainObject(t)) continue;
+      const surfacingCount = Number.isInteger(t.surfacing_count) ? t.surfacing_count : 0;
+      const state = String(t.state || '');
+      // Only transition if BOTH conditions hold:
+      //   - surfacing_count >= 3 (3-strikes threshold per CONTEXT.md D-03)
+      //   - state IN ('queued','surfaced') -- terminal states excluded so the
+      //     pre-pass is idempotent on re-runs (RESEARCH Section 11.2 rows 8+9).
+      if (surfacingCount >= 3 && (state === 'queued' || state === 'surfaced')) {
+        const next = Object.assign({}, t, {
+          state: 'dropped',
+          last_response: 'DROPPED',
+        });
+        const result = appendTension(roomSlug, next);
+        if (result && result.ok) {
+          droppedTensionIds.push(t.tension_id);
+        }
+      }
+    }
+    return { droppedTensionIds: droppedTensionIds, evaluatedCount: droppedTensionIds.length };
+  } catch (_e) {
+    return { droppedTensionIds: [], evaluatedCount: 0 };
+  }
+}
+
+/**
+ * Phase 116-03 Wave 3: read-only diagnostic listing tensions that WOULD be
+ * dropped by evaluateAndDecay. Does NOT mutate JSONL.
+ *
+ * Useful for /mos:tension status diagnostics (out of scope v1; OQ-8) and for
+ * Wave-4 telemetry traces that want to inspect candidates without firing the
+ * transition.
+ *
+ * @param {string} roomSlug
+ * @returns {Array<object>}
+ */
+function getDecayCandidates(roomSlug) {
+  try {
+    const tensions = readTensions(roomSlug);
+    return tensions.filter(function (t) {
+      if (!isPlainObject(t)) return false;
+      const surfacingCount = Number.isInteger(t.surfacing_count) ? t.surfacing_count : 0;
+      const state = String(t.state || '');
+      return surfacingCount >= 3 && (state === 'queued' || state === 'surfaced');
+    });
+  } catch (_e) {
+    return [];
+  }
+}
+
+// ---------- Module exports ----------
+
+module.exports = {
+  computeTensionId,
+  jsonlPath,
+  appendTension,
+  readTensions,
+  markSurfaced,
+  markResolved,
+  markDropped,
+  requeue,
+  evaluateAndDecay,
+  getDecayCandidates,
+  PENDING_TENSIONS_DIR,
+  VALID_STATES,
+  VALID_TYPES,
+  VALID_RESPONSES,
+};