@mindrian_os/install 1.13.0-beta.11

package/lib/core/folder-memory.cjs

@@ -0,0 +1,416 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88-01 -- folder-memory SYNC entry point
+ * ==============================================
+ * The ONE and ONLY read contract for the per-folder memory triple
+ * (ROOM.md + STATE.md + MINTO.md). Every skill, hook, statusline
+ * segment, session-start injection, guardian, and the Navigation Engine
+ * (Phase 91) consume the triple through `readTriple(sectionPath)`.
+ *
+ * The contract and field shape are documented in
+ *   .planning/phases/88-feynman-minto-memory-layer/88-CONTEXT.md
+ *     lines 99-132
+ * and in the PLAN <interfaces> block for plan 88-01. Any change to the
+ * returned shape is a cross-plan breaking change (88-06, 88-07, 88-08,
+ * 88-09, 88-10, 88-13 all consume it).
+ *
+ * Sync entry point: used by CLI hook scripts (session-start, on-stop,
+ * post-write, pre/post-compact), statusline segments, guardian, and the
+ * pre-commit gate. Mirror async twin at lib/core/folder-memory-async.cjs
+ * keeps key-set parity for MCP/Desktop callers.
+ *
+ * Pure CJS, node built-ins only, zero npm deps. Three-surface compatible
+ * by construction (CLI + Desktop MCP + Cowork).
+ *
+ * API:
+ *   readTriple(sectionPath) -> {room, state, reasoning}
+ *   readDecisionLog(sectionPath) -> decision_log array
+ *   readQuadruple(sectionPath) -> {room, state, reasoning, brain}
+ *   isQuadrupleFresh(quadruple) -> boolean
+ *   computeHealthScore(reasoning) -> number in [0,1]   (re-export)
+ *   getCurrentRoom([workDir]) -> {slug, path, source} | null   (Phase 94-01)
+ *
+ * License: BSL 1.1.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const shared = require('./folder-memory-shared.cjs');
+const invariants = require('./feynman-minto-invariants.cjs');
+
+const RESERVED = new Set(['ROOM.md', 'STATE.md', 'MINTO.md', 'TEAM-STATE.md']);
+
+function safeStatSync(p) {
+  try {
+    return fs.statSync(p);
+  } catch (_e) {
+    return null;
+  }
+}
+
+function safeReadSync(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+}
+
+function collectArtifactMtimes(sectionPath) {
+  const mtimes = [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(sectionPath);
+  } catch (_e) {
+    return mtimes;
+  }
+  for (const name of entries) {
+    if (name[0] === '.') continue;
+    if (RESERVED.has(name)) continue;
+    const abs = path.join(sectionPath, name);
+    const st = safeStatSync(abs);
+    if (!st) continue;
+    if (st.isFile() && name.endsWith('.md')) {
+      mtimes.push(st.mtimeMs);
+    }
+  }
+  return mtimes;
+}
+
+/**
+ * readTriple(sectionPath) -> {room, state, reasoning}
+ *
+ * Never throws. Missing files degrade gracefully (exists:false).
+ * Invariant violations (critical) downgrade reasoning to stale but do
+ * not zero its fields -- best-effort parse continues so consumers see
+ * as much context as possible.
+ */
+function readTriple(sectionPath) {
+  const room = { ...shared.emptyRoom() };
+  const state = { ...shared.emptyState() };
+  const reasoning = { ...shared.emptyReasoning() };
+
+  // Sentinel: if the section path itself doesn't exist, return the
+  // all-empty shell. This is the graceful-degradation contract (Test 9).
+  const sectionStat = safeStatSync(sectionPath);
+  if (!sectionStat || !sectionStat.isDirectory()) {
+    reasoning.reasoning_health_score = shared.computeHealthScore(reasoning);
+    return { room: room, state: state, reasoning: reasoning };
+  }
+
+  // ---- ROOM.md ----
+  const roomPath = path.join(sectionPath, 'ROOM.md');
+  const roomStat = safeStatSync(roomPath);
+  if (roomStat && roomStat.isFile()) {
+    const roomBuf = safeReadSync(roomPath);
+    if (roomBuf !== null) {
+      Object.assign(room, shared.parseRoomMd(roomBuf, roomStat.mtimeMs));
+    }
+  }
+
+  // ---- STATE.md ----
+  const statePath = path.join(sectionPath, 'STATE.md');
+  const stateStat = safeStatSync(statePath);
+  if (stateStat && stateStat.isFile()) {
+    const stateBuf = safeReadSync(statePath);
+    if (stateBuf !== null) {
+      Object.assign(state, shared.parseStateMd(stateBuf));
+    }
+  }
+
+  // ---- MINTO.md ----
+  const mintoPath = path.join(sectionPath, 'MINTO.md');
+  const mintoStat = safeStatSync(mintoPath);
+  if (mintoStat && mintoStat.isFile()) {
+    const mintoBuf = safeReadSync(mintoPath);
+    if (mintoBuf !== null) {
+      const parsed = shared.parseMintoMd(mintoBuf);
+      Object.assign(reasoning, parsed);
+      reasoning.exists = true;
+
+      // Ask the invariants validator for its verdict. Critical violations
+      // downgrade stale_reason to 'invariant_violation' so every downstream
+      // consumer agrees. Best-effort parse is preserved; we do NOT zero
+      // governing_thought or decision_log on invariant failure.
+      let invariantSeverity = null;
+      try {
+        const v = invariants.validate(mintoPath);
+        invariantSeverity = v.severity;
+      } catch (_e) {
+        // Validator is defensive; treat unexpected failure as warning-level
+        invariantSeverity = null;
+      }
+
+      const artifactMtimes = collectArtifactMtimes(sectionPath);
+      const stale = shared.computeStale(
+        reasoning,
+        artifactMtimes,
+        mintoStat.mtimeMs,
+        invariantSeverity
+      );
+      reasoning.is_stale = stale.is_stale;
+      reasoning.stale_reason = stale.stale_reason;
+    }
+  }
+  // If reasoning.exists is still false (no MINTO.md), the default
+  // emptyReasoning() shell already carries is_stale:true,
+  // stale_reason:'never_generated' which matches the contract.
+
+  // Compute reasoning_health_score deterministically from the parsed
+  // reasoning fields + freshness outcome.
+  reasoning.reasoning_health_score = shared.computeHealthScore(reasoning);
+
+  return { room: room, state: state, reasoning: reasoning };
+}
+
+/**
+ * readDecisionLog(sectionPath) -> Array of decision_log entries.
+ *
+ * Read-optimized for 88-09 consumer (post-compact re-injection). Same
+ * permissive shape as readTriple().reasoning.decision_log: returns ALL
+ * entries in write order (oldest first), no cap enforcement on the
+ * read side (guardian is strict; read is permissive).
+ */
+function readDecisionLog(sectionPath) {
+  const mintoPath = path.join(sectionPath, 'MINTO.md');
+  const buf = safeReadSync(mintoPath);
+  if (buf === null) return [];
+  const parsed = shared.parseMintoMd(buf);
+  return Array.isArray(parsed.decision_log) ? parsed.decision_log : [];
+}
+
+// ---------- Phase 90-04 readQuadruple (additive extension) ----------
+//
+// readQuadruple composes on top of readTriple. readTriple semantics are
+// preserved byte-for-byte; readQuadruple simply adds a fourth field
+// named "brain" that is either null (BRAIN.md absent) or a structured
+// object parsed from BRAIN.md.
+//
+// Canon Part 8 (Graph Boundary): readQuadruple is a LOCAL read. No
+// Brain MCP call is made here. The BRAIN.md file was written locally
+// by Plan 90-01 deriveSection (which is the module that DOES call
+// Brain, under chokepoint buildBrainQueryContext). Consumers
+// downstream of readQuadruple are responsible for not sending brain
+// content back into Brain query payloads.
+
+/**
+ * readQuadruple(sectionPath) -> {room, state, reasoning, brain}
+ *
+ * Additive extension of readTriple. Brain field:
+ *   - null when BRAIN.md is absent
+ *   - struct with parse_failed:true when BRAIN.md is present but
+ *     unparseable (malformed frontmatter, empty file, I/O error)
+ *   - full struct when BRAIN.md parses cleanly
+ *
+ * Never throws. Phase 88-01 readTriple signature/return unchanged.
+ */
+function readQuadruple(sectionPath) {
+  const triple = readTriple(sectionPath);
+  const brainPath = path.join(sectionPath, 'BRAIN.md');
+  const brain = shared.parseBrainMd(brainPath);
+  return shared.attachBrainToTriple(triple, brain);
+}
+
+/**
+ * isQuadrupleFresh(quadruple) -> boolean
+ *
+ * Returns true iff:
+ *   (a) reasoning.is_stale === false, AND
+ *   (b) brain is null  OR  brain.staleness === 'fresh'  OR
+ *       brain.stale_reason === 'brain_offline'
+ *
+ * Rationale: brain-offline is a transient network condition, not a
+ * derivation-staleness signal. A quadruple whose BRAIN.md is stale
+ * because Brain is temporarily unreachable is still "fresh enough" for
+ * consumers that don't require the brain signal. A brain that is stale
+ * for ANY other reason (governing_thought_changed, age_exceeded,
+ * brain_graph_version_mismatch, derivation_timeout) marks the
+ * quadruple as not-fresh.
+ *
+ * Pure function -- no I/O, no exceptions.
+ */
+function isQuadrupleFresh(quadruple) {
+  if (!quadruple || typeof quadruple !== 'object') return false;
+  const reasoning = quadruple.reasoning;
+  if (!reasoning || reasoning.is_stale !== false) return false;
+  const brain = quadruple.brain;
+  if (brain === null || brain === undefined) return true;
+  if (brain.staleness === 'fresh') return true;
+  if (brain.stale_reason === 'brain_offline') return true;
+  return false;
+}
+
+// ---------- Phase 94-01 getCurrentRoom (statusline canonical read) ----------
+//
+// Lawrence Aronhime hit the v1.11.0 bug "look at the bottom. It still says
+// core power" four times in 38 minutes because scripts/context-monitor was
+// deriving the room name from a stale source. This function anchors the
+// canonical contract: STATE.md frontmatter current_room is the source of
+// truth; statusline is a derived read-only view.
+//
+// Canon Part 7 (Reuse Before Build): composes resolveRoom() from room-ops-
+// shared and reuses the same minimal frontmatter sniff readTriple already
+// uses (no new YAML lib). Canon Part 4: read-only function, never writes.
+// Canon Part 8: pure local; never queries Brain.
+
+/**
+ * Resolve the canonical STATE.md path for the active room.
+ *
+ * Resolution order (first match wins):
+ *   1. <workDir>/.rooms/registry.json -> active room's STATE.md
+ *   2. <workDir>/room/STATE.md            (legacy default room)
+ *   3. <workDir>/STATE.md                  (workDir IS the room)
+ *
+ * Returns absolute path string or null. Pure I/O probes; never throws.
+ *
+ * @param {string} workDir
+ * @returns {string|null}
+ */
+function resolveCanonicalStateMd(workDir) {
+  let resolved;
+  try {
+    resolved = path.resolve(workDir);
+  } catch (_e) {
+    return null;
+  }
+
+  // Strategy 1: registry-driven active room.
+  const registryPath = path.join(resolved, '.rooms', 'registry.json');
+  const regStat = safeStatSync(registryPath);
+  if (regStat && regStat.isFile()) {
+    const regBuf = safeReadSync(registryPath);
+    if (regBuf !== null) {
+      try {
+        const reg = JSON.parse(regBuf);
+        if (reg && reg.active && reg.rooms && reg.rooms[reg.active]) {
+          const roomDir = path.resolve(resolved, reg.rooms[reg.active].path);
+          const candidate = path.join(roomDir, 'STATE.md');
+          const st = safeStatSync(candidate);
+          if (st && st.isFile()) return candidate;
+        }
+      } catch (_e) { /* fall through */ }
+    }
+  }
+
+  // Strategy 2: legacy room/ dir.
+  const legacy = path.join(resolved, 'room', 'STATE.md');
+  const legacyStat = safeStatSync(legacy);
+  if (legacyStat && legacyStat.isFile()) return legacy;
+
+  // Strategy 3: workDir IS a room.
+  const direct = path.join(resolved, 'STATE.md');
+  const directStat = safeStatSync(direct);
+  if (directStat && directStat.isFile()) return direct;
+
+  return null;
+}
+
+/**
+ * Extract the YAML frontmatter block from a markdown buffer, then walk
+ * its lines for the `current_room` key. Returns the parsed slug string
+ * or null on every failure mode (no frontmatter, malformed, key absent).
+ *
+ * Strips surrounding single/double quotes and whitespace from the value.
+ * Treats explicit `null` / empty string as absent.
+ *
+ * @param {string} buf
+ * @returns {string|null}
+ */
+function parseCurrentRoomField(buf) {
+  if (typeof buf !== 'string' || buf.length === 0) return null;
+
+  // Frontmatter MUST open with --- on the very first line. This is a
+  // tighter sniff than parseStateMd does, but the canonical write surface
+  // (the /mos:rooms skill) emits clean frontmatter every time.
+  if (buf.indexOf('---') !== 0) return null;
+  if (buf.length < 4) return null;
+  if (buf[3] !== '\n' && buf[3] !== '\r') return null;
+
+  // Locate the closing ---.
+  const rest = buf.slice(buf.indexOf('\n') + 1);
+  const closeMatch = rest.match(/^---\s*$/m);
+  if (!closeMatch) return null;
+  const fmText = rest.slice(0, closeMatch.index);
+
+  // Walk frontmatter lines for current_room.
+  const lines = fmText.split(/\r?\n/);
+  for (const raw of lines) {
+    if (raw.length === 0) continue;
+    if (/^\s*#/.test(raw)) continue;
+    const m = raw.match(/^current_room\s*:\s*(.+?)\s*$/);
+    if (!m) continue;
+    let value = m[1].trim();
+    if (value.length === 0) return null;
+    if (value === 'null' || value === '~') return null;
+
+    // Strip surrounding quotes (single, double, or matched pairs).
+    if (
+      (value[0] === '"' && value[value.length - 1] === '"') ||
+      (value[0] === "'" && value[value.length - 1] === "'")
+    ) {
+      if (value.length >= 2) value = value.slice(1, -1).trim();
+    }
+    if (value.length === 0) return null;
+
+    // Reject obvious garbage that the YAML-malformed test produces. A
+    // valid slug is non-empty, non-whitespace, and does not contain
+    // unescaped colons (which would imply a nested structure we cannot
+    // honor without a real YAML parser).
+    if (value.indexOf(':') !== -1) return null;
+
+    return value;
+  }
+  return null;
+}
+
+/**
+ * getCurrentRoom([workDir]) -> {slug, path, source: 'state_md'} | null
+ *
+ * Reads the canonical active-room slug from STATE.md frontmatter
+ * `current_room` field. Resolution order matches resolveCanonicalStateMd.
+ * Pure read; never writes; never throws.
+ *
+ * Returns null when STATE.md is missing, lacks frontmatter, lacks the
+ * current_room field, or has malformed YAML. Consumers (scripts/context-
+ * monitor, /mos:status, etc) treat null as "fall back to git rev-parse"
+ * per Canon Part 3 Tier 0 graceful degradation.
+ *
+ * Phase 94-01 -- statusline canonical source. Lawrence reproducer fence.
+ *
+ * @param {string} [workDir] - workspace root (default process.cwd())
+ * @returns {{slug: string, path: string, source: 'state_md'} | null}
+ */
+function getCurrentRoom(workDir) {
+  const root = workDir || process.cwd();
+  const statePath = resolveCanonicalStateMd(root);
+  if (!statePath) return null;
+
+  const buf = safeReadSync(statePath);
+  if (buf === null) return null;
+
+  let slug;
+  try {
+    slug = parseCurrentRoomField(buf);
+  } catch (_e) {
+    return null;
+  }
+  if (slug === null) return null;
+
+  return {
+    slug: slug,
+    path: statePath,
+    source: 'state_md',
+  };
+}
+
+module.exports = {
+  readTriple: readTriple,
+  readDecisionLog: readDecisionLog,
+  readQuadruple: readQuadruple,
+  isQuadrupleFresh: isQuadrupleFresh,
+  computeHealthScore: shared.computeHealthScore,
+  getCurrentRoom: getCurrentRoom,
+};