@jaimevalasek/aioson 1.9.3 → 1.17.2

package/src/neural-chain-telemetry.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Neural Chain — shared chain_audit telemetry emit helper.
+ *
+ * Single emitter used by both the CLI command (`src/commands/chain-audit.js`)
+ * and the post-session hook (`src/neural-chain-agent-ingest.js`) so payload
+ * shape is identical across code paths (BR-NC-10).
+ *
+ * Spec payload schema (BR-NC-10), 8 required fields:
+ *   feature_slug         — string | null
+ *   source_files         — string[] (the files edited in this session, plural)
+ *   impacts_found        — number | null (null on query failure)
+ *   auto_fixable_count   — number (per BR-NC-02/03 classification)
+ *   noise_file           — string | null (path written, if any)
+ *   tokens_used          — number (V1 placeholder = 0; M2 hooks LLM-mediated path)
+ *   duration_ms          — number (audit query elapsed; 0 on no-op)
+ *   error                — string | null
+ *
+ * Emitters may attach extra context fields (e.g. `agent`, `autonomy_mode`,
+ * `chain_auto_threshold`, `ingest_stats`, `skipped_reason`) on top of the
+ * required schema — those are passed through verbatim.
+ *
+ * EC-NC-05 no-op event (empty artifact list) also populates `duration_ms = 0`
+ * and `error = null` so downstream aggregation never has to special-case the
+ * skip path. Hotfix v1.17.1 — bug-found-003 from @tester gap-fill audit.
+ */
+
+const REQUIRED_FIELDS = Object.freeze([
+  'feature_slug',
+  'source_files',
+  'impacts_found',
+  'auto_fixable_count',
+  'noise_file',
+  'tokens_used',
+  'duration_ms',
+  'error'
+]);
+
+function normalizeSourceFiles(value) {
+  if (Array.isArray(value)) return value.slice();
+  if (value === null || value === undefined) return [];
+  return [String(value)];
+}
+
+function buildChainAuditPayload({
+  feature_slug = null,
+  source_files = [],
+  impacts_found = 0,
+  auto_fixable_count = 0,
+  noise_file = null,
+  tokens_used = 0,
+  duration_ms = 0,
+  error = null,
+  ...extras
+} = {}) {
+  return {
+    feature_slug,
+    source_files: normalizeSourceFiles(source_files),
+    impacts_found,
+    auto_fixable_count,
+    noise_file,
+    tokens_used,
+    duration_ms,
+    error,
+    ...extras
+  };
+}
+
+function emitChainAuditEvent(db, { agent = null, message = 'chain:audit', ...payloadOverrides } = {}) {
+  if (!db || typeof db.prepare !== 'function') return false;
+  const payload = buildChainAuditPayload(payloadOverrides);
+  try {
+    db.prepare(`
+      INSERT INTO execution_events (event_type, agent_name, message, payload_json, created_at)
+      VALUES ('chain_audit', ?, ?, ?, ?)
+    `).run(agent, message, JSON.stringify(payload), new Date().toISOString());
+    return true;
+  } catch (_) {
+    // BR-NC-10 best-effort: telemetry failure must never propagate to the caller.
+    return false;
+  }
+}
+
+module.exports = {
+  buildChainAuditPayload,
+  emitChainAuditEvent,
+  normalizeSourceFiles,
+  REQUIRED_FIELDS
+};

package/src/operator-memory/conflict.js

@@ -0,0 +1,202 @@
+'use strict';
+
+/**
+ * operator-memory — conflict policy + warning surface (Phase 4, v1.15.0).
+ *
+ * V1 binary policy (PMD-09): project rules in `.aioson/rules/` always win.
+ * Operator decisions are unchanged on conflict — only a stderr warning is
+ * emitted, debounced per (decision_slug, rule_path) pair via _conflict_state.json
+ * with a 60s window (AC-P4-03).
+ *
+ * Detection (V1 keyword-based — V2 will move to LLM-tagged):
+ *   1. Rule frontmatter must opt in: `conflicts_with_signal_types: [authorization, ...]`
+ *      Rules without this field generate zero false positives (additive policy).
+ *   2. Operator decision's signal_type must intersect rule's `conflicts_with_signal_types`.
+ *   3. Keyword overlap ≥ 2 between rule body and decision body (case-insensitive,
+ *      stopwords filtered). Configurable via env `AIOSON_OPERATOR_CONFLICT_KEYWORD_THRESHOLD`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+
+const DEFAULT_KEYWORD_THRESHOLD = 2;
+const DEFAULT_DEBOUNCE_MS = 60_000;
+const CONFLICT_STATE_FILE = '_conflict_state.json';
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'of', 'to', 'for', 'in', 'on', 'with', 'is', 'be',
+  'que', 'de', 'em', 'para', 'sem', 'com', 'um', 'uma', 'os', 'as', 'no', 'na'
+]);
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w && !STOPWORDS.has(w) && w.length >= 3);
+}
+
+function keywordOverlap(textA, textB) {
+  const a = new Set(tokenize(textA));
+  const b = new Set(tokenize(textB));
+  if (a.size === 0 || b.size === 0) return 0;
+  let overlap = 0;
+  for (const t of a) if (b.has(t)) overlap += 1;
+  return overlap;
+}
+
+function parseRuleFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  let inList = null;
+  for (const rawLine of m[1].split('\n')) {
+    if (inList) {
+      const listItem = rawLine.match(/^\s+-\s+(.*)$/);
+      if (listItem) {
+        out[inList].push(listItem[1].trim().replace(/^['"]|['"]$/g, ''));
+        continue;
+      } else if (rawLine.trim() === '' || /^[a-z_]+:/.test(rawLine)) {
+        inList = null;
+        // fall through to parse this line as regular field
+      }
+    }
+    const arrayLineMatch = rawLine.match(/^([a-z_]+):\s*\[(.*)\]$/);
+    if (arrayLineMatch) {
+      out[arrayLineMatch[1]] = arrayLineMatch[2].split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+      continue;
+    }
+    const listStartMatch = rawLine.match(/^([a-z_]+):\s*$/);
+    if (listStartMatch) {
+      out[listStartMatch[1]] = [];
+      inList = listStartMatch[1];
+      continue;
+    }
+    const fieldMatch = rawLine.match(/^([a-z_]+):\s*(.+)$/);
+    if (fieldMatch) {
+      let v = fieldMatch[2].trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      out[fieldMatch[1]] = v;
+    }
+  }
+  return out;
+}
+
+function readRule(rulePath) {
+  const content = fs.readFileSync(rulePath, 'utf8');
+  const fm = parseRuleFrontmatter(content);
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/, '');
+  return { frontmatter: fm || {}, body, path: rulePath };
+}
+
+function scanProjectRules(projectRoot) {
+  const rulesDir = path.join(projectRoot, '.aioson', 'rules');
+  if (!fs.existsSync(rulesDir)) return [];
+  const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+  return files.map((f) => readRule(path.join(rulesDir, f)));
+}
+
+/**
+ * Detect conflicts between loaded operator decisions and project rules.
+ *
+ * @param {Array<object>} decisions — decisions to check (e.g. matched by preflightLoad)
+ * @param {Array<object>} rules — output of scanProjectRules(projectRoot)
+ * @param {object} options — { threshold }
+ * @returns {Array<{decision_slug, rule_path, rule_basename, reason, severity, overlap}>}
+ */
+function detectConflicts(decisions, rules, options = {}) {
+  const threshold = options.threshold || DEFAULT_KEYWORD_THRESHOLD;
+  const conflicts = [];
+
+  for (const decision of decisions) {
+    for (const rule of rules) {
+      const conflictSignals = rule.frontmatter.conflicts_with_signal_types;
+      if (!Array.isArray(conflictSignals) || conflictSignals.length === 0) continue;
+      if (!conflictSignals.includes(decision.signal_type)) continue;
+      const overlap = keywordOverlap(rule.body, decision.body || decision.proposal || '');
+      if (overlap >= threshold) {
+        conflicts.push({
+          decision_slug: decision.slug,
+          rule_path: rule.path,
+          rule_basename: path.basename(rule.path),
+          severity: 'warning',
+          overlap,
+          reason: `keyword overlap=${overlap} ≥ threshold=${threshold}, signal_type=${decision.signal_type} in rule.conflicts_with_signal_types`
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+function formatConflictWarning(conflict) {
+  return `⚠ Operator memory '${conflict.decision_slug}' conflicts with project rule '${conflict.rule_basename}'. Project rule applies.`;
+}
+
+function conflictStatePath(identity) {
+  return path.join(getStorageRoot(identity), CONFLICT_STATE_FILE);
+}
+
+function loadConflictState(identity) {
+  const p = conflictStatePath(identity);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveConflictState(identity, state) {
+  const p = conflictStatePath(identity);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Filter conflicts to those whose debounce window has elapsed.
+ * Updates state file with new last_warned_at timestamps for emitted ones.
+ *
+ * @returns {Array} subset of conflicts that should be emitted right now
+ */
+function debounceConflicts(identity, conflicts, options = {}) {
+  if (conflicts.length === 0) return [];
+  const debounceMs = options.debounceMs || DEFAULT_DEBOUNCE_MS;
+  const state = loadConflictState(identity);
+  const now = Date.now();
+  const toEmit = [];
+  let stateChanged = false;
+  for (const c of conflicts) {
+    const key = `${c.decision_slug}::${c.rule_basename}`;
+    const last = state[key];
+    if (!last || (now - new Date(last).getTime()) >= debounceMs) {
+      toEmit.push(c);
+      state[key] = new Date(now).toISOString();
+      stateChanged = true;
+    }
+  }
+  if (stateChanged) {
+    try { saveConflictState(identity, state); } catch { /* non-fatal */ }
+  }
+  return toEmit;
+}
+
+module.exports = {
+  detectConflicts,
+  debounceConflicts,
+  formatConflictWarning,
+  scanProjectRules,
+  readRule,
+  parseRuleFrontmatter,
+  keywordOverlap,
+  tokenize,
+  loadConflictState,
+  saveConflictState,
+  DEFAULT_KEYWORD_THRESHOLD,
+  DEFAULT_DEBOUNCE_MS,
+  CONFLICT_STATE_FILE
+};

package/src/operator-memory/decay.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * operator-memory — per-category TTL decay engine (Phase 5, v1.16.0).
+ *
+ * PMD-03: category half-life (identity=365d, autonomy=180d, tooling=90d, default=90d).
+ * Decay prompt fires when (now - last_reinforced) >= half_life, debounced 30d per slug
+ * via _decay_state.json.
+ *
+ * Per-category override via env: AIOSON_OPERATOR_DECAY_<CATEGORY>_DAYS (e.g.
+ * AIOSON_OPERATOR_DECAY_IDENTITY_DAYS=730 for 2-year identity persistence).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { getStorageRoot } = require('./storage');
+const { readDecision } = require('./decision');
+const { listDecisionSlugs } = require('./index-md');
+
+const DECAY_STATE_FILE = '_decay_state.json';
+
+const HALF_LIFE_DAYS_DEFAULT = {
+  identity: 365,
+  autonomy: 180,
+  tooling: 90,
+  default: 90
+};
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_PROMPT_DEBOUNCE_DAYS = 30;
+
+function halfLifeForCategory(category) {
+  const envKey = `AIOSON_OPERATOR_DECAY_${String(category).toUpperCase()}_DAYS`;
+  const override = process.env[envKey];
+  if (override && !Number.isNaN(Number(override))) {
+    return Number(override);
+  }
+  return HALF_LIFE_DAYS_DEFAULT[category] ?? HALF_LIFE_DAYS_DEFAULT.default;
+}
+
+function decayStatePath(identity) {
+  return path.join(getStorageRoot(identity), DECAY_STATE_FILE);
+}
+
+function loadDecayState(identity) {
+  const p = decayStatePath(identity);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveDecayState(identity, state) {
+  const p = decayStatePath(identity);
+  const tmp = `${p}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+  fs.renameSync(tmp, p);
+}
+
+/**
+ * Compute days since last_reinforced for a decision.
+ */
+function daysSinceReinforced(decision, now = Date.now()) {
+  const reinforced = new Date(decision.last_reinforced || decision.promoted_at || 0).getTime();
+  if (!reinforced) return Infinity;
+  return Math.floor((now - reinforced) / DAY_MS);
+}
+
+/**
+ * Identify stale decisions whose decay-prompt debounce window has elapsed.
+ *
+ * @returns {Array<{slug, category, days_stale, half_life}>} candidates to surface
+ */
+function findStaleDecisions(identity, options = {}) {
+  const now = options.now || Date.now();
+  const debounceDays = options.debounceDays ?? DEFAULT_PROMPT_DEBOUNCE_DAYS;
+  const state = loadDecayState(identity);
+  const slugs = listDecisionSlugs(identity);
+  const stale = [];
+
+  for (const slug of slugs) {
+    const decision = readDecision(identity, slug);
+    if (!decision) continue;
+    const category = decision.category || 'default';
+    const halfLife = halfLifeForCategory(category);
+    const daysStale = daysSinceReinforced(decision, now);
+    if (daysStale < halfLife) continue;
+
+    const last = state[slug];
+    if (last) {
+      const daysSincePrompt = Math.floor((now - new Date(last).getTime()) / DAY_MS);
+      if (daysSincePrompt < debounceDays) continue;
+    }
+    stale.push({ slug, category, days_stale: daysStale, half_life: halfLife, title: decision.body?.slice(0, 80) || slug });
+  }
+
+  return stale;
+}
+
+/**
+ * Mark a stale decision's prompt as shown (updates debounce timestamp).
+ */
+function markDecayPromptShown(identity, slug) {
+  const state = loadDecayState(identity);
+  state[slug] = new Date().toISOString();
+  saveDecayState(identity, state);
+}
+
+function formatDecayPrompt(stale) {
+  return `⏱ Memory '${stale.slug}' is ${stale.days_stale}d stale (${stale.category}, half-life=${stale.half_life}d). Still valid? aioson op:reinforce ${stale.slug} | op:forget ${stale.slug}`;
+}
+
+/**
+ * Clean up history/ entries older than maxAgeDays (default 365). Phase 5
+ * cleanup runs alongside decay sweep — hard-delete old soft-deleted items.
+ *
+ * @returns {Array<string>} paths of files removed
+ */
+function cleanupHistory(identity, options = {}) {
+  const maxAgeDays = options.maxAgeDays || 365;
+  const now = options.now || Date.now();
+  const historyDir = path.join(getStorageRoot(identity), 'history');
+  if (!fs.existsSync(historyDir)) return [];
+
+  const removed = [];
+  for (const f of fs.readdirSync(historyDir)) {
+    if (!f.endsWith('.md')) continue;
+    const full = path.join(historyDir, f);
+    try {
+      const stat = fs.statSync(full);
+      const ageDays = Math.floor((now - stat.mtimeMs) / DAY_MS);
+      if (ageDays >= maxAgeDays) {
+        fs.unlinkSync(full);
+        removed.push(full);
+      }
+    } catch { /* ignore */ }
+  }
+
+  return removed;
+}
+
+module.exports = {
+  findStaleDecisions,
+  markDecayPromptShown,
+  formatDecayPrompt,
+  cleanupHistory,
+  loadDecayState,
+  saveDecayState,
+  halfLifeForCategory,
+  daysSinceReinforced,
+  HALF_LIFE_DAYS_DEFAULT,
+  DEFAULT_PROMPT_DEBOUNCE_DAYS,
+  DECAY_STATE_FILE,
+  DAY_MS
+};